home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource4 / 237_01 / graduser.doc < prev    next >
Text File  |  1987-07-28  |  186KB  |  5,448 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                       GRAD Graphics Library User's Manual
  15.  
  16.                                  Version 1.1
  17.  
  18.  
  19.                         for IBM PC/XT/AT or compatibles
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.                                                        June 07, 1987
  36.  
  37.  
  38.                                                        By Conrad Kwok
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.                                Table of Contents
  57.  
  58.        
  59.        1   Introduction . . . . . . . . . . . . . . . . . . . . . .    1
  60.           1.1  General Information  . . . . . . . . . . . . . . . .    1
  61.           1.2  Licence  . . . . . . . . . . . . . . . . . . . . . .    2
  62.           1.3  Future Enhancements  . . . . . . . . . . . . . . . .    3
  63.        2   How to use GRAD  . . . . . . . . . . . . . . . . . . . .    4
  64.           2.1  Compile and Link . . . . . . . . . . . . . . . . . .    4
  65.           2.2  Interpretation . . . . . . . . . . . . . . . . . . .    6
  66.        3   The GRAD Frame . . . . . . . . . . . . . . . . . . . . .    7
  67.           3.1  Related Functions  . . . . . . . . . . . . . . . . .    7
  68.              3.1.1  CreateFrame . . . . . . . . . . . . . . . . . .    7
  69.              3.1.2  SelectFrame . . . . . . . . . . . . . . . . . .    8
  70.              3.1.3  RemvFrame . . . . . . . . . . . . . . . . . . .    8
  71.        4   Coordinate System  . . . . . . . . . . . . . . . . . . .   10
  72.           4.1  Physical Coordinate System . . . . . . . . . . . . .   10
  73.           4.2  Logical Coordinate System  . . . . . . . . . . . . .   10
  74.              4.2.1  Setting Origin  . . . . . . . . . . . . . . . .   10
  75.              4.2.2  Translation . . . . . . . . . . . . . . . . . .   11
  76.              4.2.3  Windowing . . . . . . . . . . . . . . . . . . .   11
  77.           4.3  Related Functions  . . . . . . . . . . . . . . . . .   11
  78.              4.3.1  SetOrg  . . . . . . . . . . . . . . . . . . . .   12
  79.              4.3.2  RelOrg  . . . . . . . . . . . . . . . . . . . .   12
  80.           4.4  Summary  . . . . . . . . . . . . . . . . . . . . . .   12
  81.        5   Setting Window . . . . . . . . . . . . . . . . . . . . .   13
  82.           5.1  Function Description . . . . . . . . . . . . . . . .   13
  83.              5.1.1  ResetWin  . . . . . . . . . . . . . . . . . . .   13
  84.              5.1.2  SetWin  . . . . . . . . . . . . . . . . . . . .   13
  85.           5.2  Example  . . . . . . . . . . . . . . . . . . . . . .   14
  86.        6   GRAD Environment . . . . . . . . . . . . . . . . . . . .   15
  87.           6.1  Functions Description  . . . . . . . . . . . . . . .   15
  88.              6.1.1  EnvSave . . . . . . . . . . . . . . . . . . . .   15
  89.              6.1.2  EnvRsto . . . . . . . . . . . . . . . . . . . .   16
  90.        7   Selection of Plot Type . . . . . . . . . . . . . . . . .   16
  91.           7.1  Related Function . . . . . . . . . . . . . . . . . .   17
  92.              7.1.1  PlotType  . . . . . . . . . . . . . . . . . . .   17
  93.        8   Dot Plotting and Line Drawing  . . . . . . . . . . . . .   18
  94.           8.1  Functions Description  . . . . . . . . . . . . . . .   18
  95.              8.1.1  Dot . . . . . . . . . . . . . . . . . . . . . .   18
  96.              8.1.2  SetStyle  . . . . . . . . . . . . . . . . . . .   18
  97.              8.1.3  HorzLine  . . . . . . . . . . . . . . . . . . .   19
  98.              8.1.4  VertLine  . . . . . . . . . . . . . . . . . . .   19
  99.           8.2  Efficiency Consideration . . . . . . . . . . . . . .   20
  100.        9   Circle, Ellipse and Arc  . . . . . . . . . . . . . . . .   21
  101.           9.1  Functions Description  . . . . . . . . . . . . . . .   21
  102.              9.1.1  Circle  . . . . . . . . . . . . . . . . . . . .   21
  103.              9.1.2  Ellipse . . . . . . . . . . . . . . . . . . . .   22
  104.              9.1.3  FillCircle  . . . . . . . . . . . . . . . . . .   22
  105.              9.1.4  FillEllipse . . . . . . . . . . . . . . . . . .   23
  106.              9.1.5  Arc1  . . . . . . . . . . . . . . . . . . . . .   23
  107.              9.1.6  Earc1 . . . . . . . . . . . . . . . . . . . . .   24
  108.              9.1.7  Arc2  . . . . . . . . . . . . . . . . . . . . .   25
  109.              9.1.8  Earc2 . . . . . . . . . . . . . . . . . . . . .   26
  110.              9.1.9  ArcPoint  . . . . . . . . . . . . . . . . . . .   27
  111.           9.2  Hints  . . . . . . . . . . . . . . . . . . . . . . .   27
  112.        10  4-connected Region Filling . . . . . . . . . . . . . . .   29
  113.           10.1  Functions Description . . . . . . . . . . . . . . .   29
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.              10.1.1  SolidFill  . . . . . . . . . . . . . . . . . .   29
  122.              10.1.2  PatternFill  . . . . . . . . . . . . . . . . .   30
  123.           10.2  Hints . . . . . . . . . . . . . . . . . . . . . . .   31
  124.        11  Text Characters Related Functions  . . . . . . . . . . .   32
  125.           Introduction  . . . . . . . . . . . . . . . . . . . . . .   32
  126.           11.1  Functions Description . . . . . . . . . . . . . . .   32
  127.              11.1.1  LoadFont . . . . . . . . . . . . . . . . . . .   32
  128.              11.1.2  SelectFont . . . . . . . . . . . . . . . . . .   33
  129.              11.1.3  RemvFont . . . . . . . . . . . . . . . . . . .   33
  130.              11.1.4  WriteStr . . . . . . . . . . . . . . . . . . .   34
  131.              11.1.5  ReadStr  . . . . . . . . . . . . . . . . . . .   36
  132.              11.1.6  NextXY . . . . . . . . . . . . . . . . . . . .   37
  133.        12  Block Operations . . . . . . . . . . . . . . . . . . . .   38
  134.           12.1  Function Description  . . . . . . . . . . . . . . .   38
  135.              12.1.1  BlockCopy  . . . . . . . . . . . . . . . . . .   38
  136.              12.1.2  BlockSave  . . . . . . . . . . . . . . . . . .   39
  137.              12.1.3  BlockLoad  . . . . . . . . . . . . . . . . . .   39
  138.        13  Frame Printing . . . . . . . . . . . . . . . . . . . . .   41
  139.           13.1  Function Description  . . . . . . . . . . . . . . .   41
  140.              13.1.1  PrintFrame . . . . . . . . . . . . . . . . . .   41
  141.        14  The DRAW function  . . . . . . . . . . . . . . . . . . .   44
  142.           14.1  Draw  . . . . . . . . . . . . . . . . . . . . . . .   44
  143.        15  Miscellaneous Functions  . . . . . . . . . . . . . . . .   48
  144.           15.1  Functions Description . . . . . . . . . . . . . . .   48
  145.              15.1.1  GRADinit . . . . . . . . . . . . . . . . . . .   48
  146.              15.1.2  cleanup  . . . . . . . . . . . . . . . . . . .   48
  147.              15.1.3  XHLine . . . . . . . . . . . . . . . . . . . .   49
  148.              15.1.4  writec . . . . . . . . . . . . . . . . . . . .   49
  149.        16  Advance Functions  . . . . . . . . . . . . . . . . . . .   51
  150.           16.1  Functions Description . . . . . . . . . . . . . . .   51
  151.              16.1.1  calcaddr . . . . . . . . . . . . . . . . . . .   51
  152.              16.1.2  exchange . . . . . . . . . . . . . . . . . . .   51
  153.              16.1.3  fr_read  . . . . . . . . . . . . . . . . . . .   52
  154.              16.1.4  fr_write . . . . . . . . . . . . . . . . . . .   52
  155.              16.1.5  phyaddr  . . . . . . . . . . . . . . . . . . .   52
  156.              16.1.6  writetype  . . . . . . . . . . . . . . . . . .   53
  157.        17  System Dependent Functions . . . . . . . . . . . . . . .   54
  158.           17.1  Functions Description . . . . . . . . . . . . . . .   54
  159.              17.1.1  settext  . . . . . . . . . . . . . . . . . . .   54
  160.              17.1.2  setgraph . . . . . . . . . . . . . . . . . . .   54
  161.              17.1.3  initjlsr . . . . . . . . . . . . . . . . . . .   54
  162.              17.1.4  cleanjlsr  . . . . . . . . . . . . . . . . . .   55
  163.              17.1.5  dumpjlsr . . . . . . . . . . . . . . . . . . .   55
  164.        18  GRAD Global Variables  . . . . . . . . . . . . . . . . .   56
  165.           18.1  TEN_MS  . . . . . . . . . . . . . . . . . . . . . .   56
  166.           18.2  DOTVALUE  . . . . . . . . . . . . . . . . . . . . .   56
  167.           18.3  PRE_GRAD_ERR_LEVEL, POST_GRAD_ERR_LEVEL . . . . . .   56
  168.           18.4  PRE_ERROR_FUNC, POST_ERROR_FUNC . . . . . . . . . .   56
  169.           18.5  SPACING_FUNC  . . . . . . . . . . . . . . . . . . .   57
  170.           18.6  XLIMIT, YLIMIT  . . . . . . . . . . . . . . . . . .   57
  171.           18.7  ORGX, ORGY  . . . . . . . . . . . . . . . . . . . .   57
  172.           18.8  WINX1, WINX2, WINY1, WINY2  . . . . . . . . . . . .   58
  173.        19  Advance Topics . . . . . . . . . . . . . . . . . . . . .   59
  174.           19.1  Error Handling  . . . . . . . . . . . . . . . . . .   59
  175.           19.2  Using SPACING_FUNC  . . . . . . . . . . . . . . . .   60
  176.        20  Sample Programs  . . . . . . . . . . . . . . . . . . . .   62
  177.           20.1  MPrint and Interp . . . . . . . . . . . . . . . . .   62
  178.           20.2  Rotate  . . . . . . . . . . . . . . . . . . . . . .   63
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.           20.3  Size  . . . . . . . . . . . . . . . . . . . . . . .   64
  187.           20.4  DispFont  . . . . . . . . . . . . . . . . . . . . .   64
  188.           20.5  SwPrt (Sideway) . . . . . . . . . . . . . . . . . .   64
  189.           20.6  Tex2GRAD  . . . . . . . . . . . . . . . . . . . . .   65
  190.        Appendix A : Customizing of Printer Control Codes  . . . . .   67
  191.           General Information . . . . . . . . . . . . . . . . . . .   67
  192.           EPSON FX-80 Driver Case Study . . . . . . . . . . . . . .   69
  193.           OKI ML192 Driver Case Study . . . . . . . . . . . . . . .   69
  194.           Additional Information  . . . . . . . . . . . . . . . . .   70
  195.        Appendix B : Customizing of Output Device  . . . . . . . . .   71
  196.        Appendix C : Font File Structure . . . . . . . . . . . . . .   72
  197.           Fixed Size Character (type 0) . . . . . . . . . . . . . .   72
  198.           Variable Size Character (type 1)  . . . . . . . . . . . .   73
  199.        Appendix D : Block File Structure  . . . . . . . . . . . . .   74
  200.        Appendix E : Functions Summary . . . . . . . . . . . . . . .   75
  201.        Appendix F : System Limits . . . . . . . . . . . . . . . . .   76
  202.           Program Limits  . . . . . . . . . . . . . . . . . . . . .   76
  203.           Configuration Limits  . . . . . . . . . . . . . . . . . .   76
  204.        Appendix G : Error Messages  . . . . . . . . . . . . . . . .   78
  205.        Appendix H : List of Header Files  . . . . . . . . . . . . .   79
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.        GRAD User's Manual                                    June 7, 1987
  250.  
  251.        1   Introduction
  252.  
  253.        1.1  General Information
  254.  
  255.             GRAD  is a  graphics functions library  for program compiled
  256.        with Microsoft  C  compiler  V4.0  in  small  model.  The library
  257.        contains most  functions  you  normally  expected  in  a graphics
  258.        library plus a number of unique features.
  259.             
  260.             This  brief summary is  to  introduce  you  features in GRAD
  261.        version 1.1. Each of these features is described in detail in the
  262.        documentation.
  263.             
  264.          a. GRAD  supports  color graphics  card  in 640  X 200 graphics
  265.             mode,  Hercules 720  X 348  graphics mode and JLASER (2560 X
  266.             3162). Other output device can be configured.
  267.          
  268.          b. It can create multiple  virtual screens of  very large size.
  269.             which  is  limited by  memory.  That  means  you  can create
  270.             graphics even you do not have a graphics display screen.
  271.          
  272.          c. Functions are provided to maintain windows.
  273.          
  274.          d. Nearly all  low  level  functions  are  written  in assembly
  275.             language to provide speed.  The result below  is obtained by
  276.             running the program BRENCH on an AT compatible (8MHz, 1 wait
  277.             state). All library functions when compiled with Microsoft C
  278.             compiler  use   8088   codes  option.   All   times  are  in
  279.             millisecond.
  280.          
  281.                                  Hercules Card         Virtual Screen
  282.             a loop                  0.0023               0.0023
  283.             Horizontal Line         0.38                 0.27
  284.              (length 300)
  285.             Horiz. Line width 20    6.2                  4.3
  286.             Vertical Line           8.5                  5.7
  287.              (length 300)
  288.             Vert. Line width 2      8.5                  5.7
  289.             Vert. Line width 32    17.0                 11.3
  290.             Circle radius 100      25.5                 28.3
  291.             Ellipse both axes
  292.                is 100 pixels       30.5                 33.3
  293.             
  294.             When drawing a horizontal line, it takes about 1 microsecond
  295.             per pixel on average!
  296.             
  297.          e. The  whole   library  use  integer   arithmetic  only.  This
  298.             guarantees  high speed operations when executed without math
  299.             coprocessor and keep the program size small.
  300.          
  301.          f. Besides simple functions such as dot,  line, circle, ellipse
  302.             ...etc., high speed arc drawing and region filling functions
  303.             are also included.
  304.          
  305.          g. Screen  printing is provided  as standard  function in GRAD.
  306.             Many  different  options  are  provided  such  as  different
  307.             printing density and mixed printing of text and graphics.
  308.          
  309.  
  310.                                       - 1 -
  311.  
  312.  
  313.  
  314.        GRAD User's Manual                                    June 7, 1987
  315.  
  316.          h. GRAD provides functions for high speed and high quality text
  317.             display.
  318.          
  319.          i. The whole screen or part of a screen can be saved, loaded or
  320.             copied.
  321.          
  322.             
  323.             Several sample  programs  with practical  value are included
  324.        such as  sideway printing  and text  and graphics  merge printing
  325.        programs.
  326.  
  327.        
  328.        1.2  Licence
  329.  
  330.             You may freely  copy  and distribute  the  GRAD  library and
  331.        related programs provided that:
  332.          
  333.          a. The  whole  library  and  supporting  files   including  the
  334.             documentation and sample  programs  are not modified  in any
  335.             way.  However,  you  may modify  those  source  programs and
  336.             include them in the distribution in addition to the original
  337.             one.  For  example,  you have writen a driver  for different
  338.             graphics  display  card  or  different   printer,   you  are
  339.             encouraged to include that in the distribution and also send
  340.             a copy  to  me  such  that  I may include  that  in standard
  341.             distribution when next version is available.
  342.          
  343.          b. No price or other consideration is charged.  However a small
  344.             distribution cost may be charged for the cost  of  the disk,
  345.             shipping and handling.
  346.          
  347.             
  348.             You may freely distribute your programs containing  the GRAD
  349.        library code provided that:
  350.          
  351.          a. The   following   message   is  included  in   your  program
  352.             documentation.
  353.                This program  contains codes from the  GRAD graphics
  354.                library written by Conrad Kwok.  GRAD library can be
  355.                obtained by downloading from  BBS or  by sending $15
  356.                to the address below:
  357.               
  358.                        Mr. Conrad Kwok
  359.                        9228 Vancouver Drive
  360.                        Sacramento, CA 95826            
  361.          
  362.          b. The program must  be  in  public domain or  a user supported
  363.             program.
  364.          
  365.  
  366.        If your program does  not meet  the above requirements,  you must
  367.        get my  written  permission  prior  to  the  distribution  of you
  368.        program(s).
  369.  
  370.             If you find this library and the related  programs useful, a
  371.        contribution of  $20  or whatever  you  think  it  worth  will be
  372.        appreciated.  With  each  contribution  of $20  or more, one will
  373.        receives next major update of the library.
  374.  
  375.                                       - 2 -
  376.  
  377.  
  378.  
  379.        GRAD User's Manual                                    June 7, 1987
  380.  
  381.             
  382.             With  the contribution  of  $60  or more,  you  can  get the
  383.        commented source code of the latest version of GRAD library and a
  384.        programmer  reference  containing  information  of  the  internal
  385.        structure and  algorithms used.  The source code is  written in C
  386.        and  8088  assembly language.  The source code is copyrighted and
  387.        you are not allowed to distribute the source code in any form.
  388.             
  389.             Please send your contribution,  comments and suggests to the
  390.        address below:
  391.               
  392.                        Mr. Conrad Kwok
  393.                        9228 Vancouver Drive
  394.                        Sacramento, CA 95826            
  395.  
  396.        
  397.        1.3  Future Enhancements
  398.  
  399.        a. PatternFill will be enhanced to fill any 4-Connected Regions.
  400.  
  401.        b. PatternFill will accept pattern larger than 16 by 16 pixels.
  402.  
  403.        c. 80286 option will be provided.
  404.  
  405.        d. Increase speed of characters writing.
  406.  
  407.        e. Supports Medium Model (Multi Code segment and 64K data).
  408.  
  409.        f. More functions!
  410.  
  411.        g. Of course, also your comments and suggestions.
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.                                       - 3 -
  441.  
  442.  
  443.  
  444.        GRAD User's Manual                                    June 7, 1987
  445.  
  446.        2   How to use GRAD
  447.  
  448.             There are two ways to use the GRAD functions. The obvious is
  449.        to write a program that use  the GRAD functions  and then compile
  450.        and  link  with  GRAD  library.  Another way is  to  write a GRAD
  451.        command file that call GRAD  functions using syntax  similar to C
  452.        function call.  Then use the supplied program interp or Mprint to
  453.        interpret the file.
  454.             
  455.             The first way (compile and link) requires longer time but it
  456.        may use the full power of  C and GRAD  functions.  The second way
  457.        (interpretation)  limits the user to simple  graphics drawing but
  458.        the advantage is no compilation  and link is necessary.  Hence it
  459.        is good for simple drawings and debug a  drawing before including
  460.        in the final C program.
  461.             
  462.             The compile and link method will  be described  in detail in
  463.        this chapter.  The interpretation  method  will only be described
  464.        briefly in the chapter.  Details can be found in the user's guide
  465.        for interp and Mprint in the later chapter.
  466.             
  467.             Before we go on and try the first example,  I  want  to tell
  468.        you if you don't like to see any error message (in  text  form or
  469.        in bit mapped  form)  when the program is  in  graphics mode, you
  470.        want redirect  the output  from the file to  any file  you like.
  471.  
  472.        
  473.        2.1  Compile and Link
  474.  
  475.                
  476.                Knowledge of Microsoft C compiler Version  4.0 is
  477.                assumed and small model library must be installed
  478.                
  479.                
  480.             Below is a very  simple program  that draws a  dot only. Use
  481.        your  favorite  editor  to enter  the program below and  name the
  482.        program as "onedot.c".
  483.             
  484.                #include <stdio.h>
  485.                
  486.                main ()
  487.                {
  488.                        GradInit();     /* (1) */
  489.                        setgraph();     /* (2) */
  490.                        Dot(100,100);   /* (3) */
  491.                        getch();        /* (4) */
  492.                        settext();      /* (5) */
  493.                        cleanup(0);     /* (6) */
  494.                }
  495.  
  496.             Then compile and link the program using the command line:
  497.                cl /AS /J onedot.c /link GRADLIB
  498.             
  499.             If  you don't have  any typing  mistakes  and GRADLIB  is in
  500.        current  directory or  in  the  directory  specified  in  the LIB
  501.        environment variable,  you should get the file onedot.exe without
  502.  
  503.  
  504.  
  505.                                       - 4 -
  506.  
  507.  
  508.  
  509.        GRAD User's Manual                                    June 7, 1987
  510.  
  511.        getting an error message. If you get any error, go back and check
  512.        the program and make sure that the GRADLIB is properly installed.
  513.        Otherwise, you may go ahead and execute the program "onedot.exe".
  514.             
  515.             About one to two seconds  later,  the screen will be cleared
  516.        and you should find a single dot. Pressing any key will terminate
  517.        the program and the screen will return to text mode.
  518.             
  519.             Using the  GRAD library is simple.  Now let's  return to the
  520.        source listing and  examine it line by  line.  In the program, we
  521.        called 3  GRAD functions and 2 system dependent functions and 1 C
  522.        library function.
  523.  
  524.        (1) GRADinit is to initialize  the GRAD environment.  Now it only
  525.            performs a processor speed test and assign the result  to the
  526.            global  variable  TEN_MS.  Time  dependent  functions  may do
  527.            adjustment according to the  its value such  that they behave
  528.            the same on different speed computers. Actually we don't need
  529.            GRADinit in this case but  we should always  include that for
  530.            future compatibility.
  531.  
  532.        (2) setgraph is  not  a  standard  GRAD  function.  It  is system
  533.            dependent function.  It is only necessary if you  want to use
  534.            the default configured  graphics  screen.  Its function is to
  535.            change the display mode to graphics and clear the screen.
  536.  
  537.        (3) Dot is a GRAD function that  plot a  single dot. Dot(100,100)
  538.            means plot a dot at coordinate (100,100).
  539.  
  540.        (4) getch is a C library function that reads the next key pressed
  541.            on the keyboard.
  542.  
  543.        (5) settext  again is not a standard GRAD function. It is used to
  544.            change the display mode back to text mode.
  545.  
  546.        (6) cleanup is contrary to  GRADinit.  It should be called before
  547.            exit.  If the parameter to cleanup is  non-zero, cleanup will
  548.            execute  exit  with  the  parameter  as  exit  code.  If  the
  549.            parameter is zero, it will return to the caller.
  550.  
  551.        
  552.             Instead of using command line to do compile and link, we can
  553.        also use make file to do the same job. Below is an example:
  554.             
  555.                OPTIMIZE=/Ox
  556.                OPTIONS=/AS /J $(OPTIMIZE)
  557.                
  558.                .asm.obj:
  559.                        masm /ML $*;
  560.                
  561.                .c.obj:
  562.                        msc $(OPTION) $*;
  563.                
  564.                onedot.obj:     onedot.c
  565.                
  566.                onedot.exe:     onedot.obj
  567.                        link onedot,onedot,nul,GRADLIB;
  568.  
  569.  
  570.                                       - 5 -
  571.  
  572.  
  573.  
  574.        GRAD User's Manual                                    June 7, 1987
  575.  
  576.        2.2  Interpretation
  577.  
  578.             The one line  file  below will  perform exactly the  same as
  579.        our "onedot"  program in  the last  section  by  using  interp to
  580.        interpret it.
  581.             
  582.                Dot(100,100);
  583.             
  584.        Let's suppose the file above is called "onedot.gcm". To interpret
  585.        the file by interp, type
  586.  
  587.                interp onedot.gcm
  588.  
  589.        The syntax required by interp is described in a later chapter. 
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.                                       - 6 -
  636.  
  637.  
  638.  
  639.        GRAD User's Manual                                    June 7, 1987
  640.  
  641.        3   The GRAD Frame
  642.  
  643.             A frame is a memory area where the graphics image is stored.
  644.        It can be  any size  (there  are some  limitations and  they will
  645.        discuss in next section) but it must be an rectangle. Each bit of
  646.        the memory corresponds to a pixel.  The memory area  can be video
  647.        memory or  computer  working memory.  If it is video  memory, the
  648.        graphics image can be  seen on screen.  If it  is working memory,
  649.        the frame becomes a  virtual graphics screen.  The graphics image
  650.        can  only  be seen by  dumping  to the printer or  copying to the
  651.        video memory.
  652.             
  653.             More  than one  frame can exist simultaneously  within GRAD.
  654.        However  only one  frame can be  active at one time.  Usually the
  655.        graphics video memory is predefined  as the first  frame and this
  656.        is the default active frame. It is a permanent frame so it cannot
  657.        be removed by GRAD function RemvFrame which will be  described in
  658.        next section also.
  659.             
  660.             If you are the first time reading this manual,  you may skip
  661.        over this chapter and consider the video memory as the only frame
  662.        available. All functions that apply to the video memory frame can
  663.        be applied to the other frames in the same way.
  664.  
  665.        
  666.        3.1  Related Functions
  667.  
  668.        3.1.1  CreateFrame
  669.  
  670.                frame_number=CreateFrame(horizontal,vertical);
  671.                int frame_number, horizontal, vertical;
  672.  
  673.        RETURN VALUE
  674.             A frame number.
  675.  
  676.        DESCRIPTION
  677.  
  678.             The  CreateFrame  function  will  create  a  frame  of  size
  679.        specified by  the two parameters.  However,  the  horizontal size
  680.        must be an integral multiply of 16.  If it is not, the horizontal
  681.        size will be rounded up.
  682.             
  683.             Note that the maximum physical coordinate number will be one
  684.        less than the actual size because coordinate number starts at 0.
  685.  
  686.        POSSIBLE ERROR CONDITION
  687.  
  688.        a. Insufficient Memory
  689.           Program will terminate.
  690.           
  691.        b. Too many frame exist
  692.           The maximum number of frame allowed is an system parameter. If
  693.           the number is exceed, the program will terminate.
  694.           
  695.           
  696.        EXAMPLE
  697.  
  698.                frame=CreateFrame(640,200);
  699.  
  700.                                       - 7 -
  701.  
  702.  
  703.  
  704.        GRAD User's Manual                                    June 7, 1987
  705.  
  706.  
  707.        FUNCTIONS INCLUDED
  708.  
  709.                RemvFrame
  710.  
  711.        
  712.        3.1.2  SelectFrame
  713.  
  714.                ret=SelectFrame(frame);
  715.                int ret, frame;
  716.  
  717.        RETURN VALUE
  718.  
  719.             It  will  return  the active  frame number  just  before the
  720.        execution of SelectFrame if frame  number given is valid  and the
  721.        frame exist.  Otherwise -1  will be returned and the active frame
  722.        is not changed.
  723.             
  724.        DESCRIPTION
  725.             
  726.             The function  SelectFrame select  the current  active frame.
  727.        Furthermore, the drawing window and point of origin will reset to
  728.        the same as last time when the frame is deselected.  If the frame
  729.        is the first time selected after it  is created,  the origin will
  730.        be physical coordinate (0,0)  and the window size is same  as the
  731.        frame size.
  732.             
  733.        EXAMPLE
  734.  
  735.                if ((old_frame=SelectFrame(frame))==(-1))
  736.                        printf("Frame does not exist\n");
  737.                  .   .   .
  738.                  .   .   .   Draw in the new frame
  739.                  .   .   .
  740.                SelectFrame(old_frame);  /* switch back to the */
  741.                                         /* original frame     */
  742.  
  743.        FUNCTIONS INCLUDED
  744.  
  745.                SelectFont
  746.  
  747.        
  748.        3.1.3  RemvFrame
  749.  
  750.                ret=RemvFrame(frame);
  751.                int ret, frame;
  752.  
  753.        RETURN VALUE
  754.  
  755.             A return value of 0  means successful.  A return value of -1
  756.        means the frame does not exist. If the frame type is permanent, 0
  757.        will be returned but the frame can still be selected.
  758.  
  759.        DESCRIPTION
  760.  
  761.             The function RemvFrame will remove the frame  from GRAD. The
  762.        memory occupied by the frame will be deallocated.
  763.             
  764.  
  765.                                       - 8 -
  766.  
  767.  
  768.  
  769.        GRAD User's Manual                                    June 7, 1987
  770.  
  771.        EXAMPLE
  772.  
  773.                If (RemvFrame(frame)==(-1))
  774.                        printf("Frame does not exist\n");
  775.  
  776.        FUNCTIONS INCLUDED
  777.  
  778.                CreateFrame
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.                                       - 9 -
  831.  
  832.  
  833.  
  834.        GRAD User's Manual                                    June 7, 1987
  835.  
  836.        4   Coordinate System
  837.  
  838.        4.1  Physical Coordinate System
  839.  
  840.             Each Frame can be viewed as a two dimensional plane composes
  841.        of identical rectangular pixels.  Each pixel  is  in  of  the two
  842.        states --  on  or  off (set  or reset).  If a pixel is on,  it is
  843.        represented by a dot on screen or  on printer paper  or a logical
  844.        high state in memory.
  845.             
  846.             To address a pixel,  we can use x and  y coordinate numbers.
  847.        It  is usually  represented as (x,y).  the top right  corner of a
  848.        frame is defined as the origin of the physical  coordinate system
  849.        which  as  0  x  and  y  coordinate  value  (i.e.  (0,0)).  The x
  850.        coordinate of a pixel on the same horizontal line increase  as we
  851.        move right. The y coordinate of a pixel on the same vertical line
  852.        increase  as  we  move  downwards.  This  is  different  from the
  853.        coordinate system we usually used which has y coordinate increase
  854.        as we move upwards.
  855.             
  856.             The maximum value of the coordinate  numbers are  limited by
  857.        the size  of a  frame.  For example,  the number of pixels on IBM
  858.        color graphics adapter  are 640  (horizontal) and 200 (vertical).
  859.        Therefore legal x and y coordinate numbers are 0  to 639 and 0 to
  860.        199 respectively.
  861.             
  862.             Physical coordinate  numbers are only  used  in one external
  863.        interface function.  All  other functions use  logical coordinate
  864.        numbers which will be described in the next section.
  865.  
  866.        
  867.        4.2  Logical Coordinate System
  868.  
  869.             Logical coordinate system provides a convenient way  to look
  870.        at your frame.  Initially, the logical coordinate numbers are the
  871.        same as the physical coordinate  number.  The relationship can be
  872.        changed using SetOrg and RelOrg functions which will be described
  873.        later.
  874.             
  875.             The  relationship  between logical  and  physical coordinate
  876.        system can be  described in  several ways  and  different  way of
  877.        thinking helps in  different situation.  So  I will  describe all
  878.        three ways I can think of.
  879.  
  880.        
  881.        4.2.1  Setting Origin
  882.  
  883.             The logical coordinate  system  has  the  same  size  as the
  884.        physical coordinate  system.  Each pixel is one-one corresponding
  885.        between the two systems. The difference is that any pixels within
  886.        the logical coordinate system can  be defined as the  origin.
  887.             
  888.             Suppose your  frame size  is  640  by  200.  You  can define
  889.        (300,100)  in  physical  coordinate  system as the origin  in the
  890.        logical coordinate system.  The legal range of logical coordinate
  891.        numbers  will be  -320  to +319  and -100  to +99 for the x and y
  892.        coordinates respectively.  Any attempt to write outside the legal
  893.        space will be ignored.
  894.  
  895.                                      - 10 -
  896.  
  897.  
  898.  
  899.        GRAD User's Manual                                    June 7, 1987
  900.  
  901.             
  902.             
  903.             It is  legal to  define  a point  outside  the physical
  904.             coordinate system as the origin.  For  example, you can
  905.             define (-10,-10) as the origin. Legal coordinate number
  906.             for  x and y axes  will  be  10  to  649  and 10 to 209
  907.             respectively.
  908.             
  909.  
  910.        
  911.        4.2.2  Translation
  912.  
  913.             The logical and physical  coordinate  numbers are  offset by
  914.        fixed numbers specified by you.
  915.             
  916.             An  example of  this  situation  is  when  several identical
  917.        figures are required to draw on the frame.  Instead of  repeating
  918.        the  calling sequence  with different coordinate numbers,  we can
  919.        create a  subroutine  including  the  functions  for  drawing one
  920.        figure. We call the same subroutine as many times as required and
  921.        set different translation values in between two calls.
  922.  
  923.        
  924.        4.2.3  Windowing
  925.  
  926.             Try to imagine you are standing before a large square dinner
  927.        table. On the table, there is a piece of paper (normal size) with
  928.        its sides parallel to the edges of the table.  You are  holding a
  929.        special pen will only leave mark on the paper only but not on the
  930.        table.  You can draw anywhere  on the table.  However, only those
  931.        drawings passing the paper can be seen.
  932.             
  933.             This is an analogy of the relationship  between the physical
  934.        and  logical coordinate system.  The dinner table  is the logical
  935.        coordinate  system space,  the paper is  the  physical coordinate
  936.        system (or frame)  and the GRAD  functions are the  pen.  You can
  937.        place the frame anywhere within the logical coordinate space.
  938.             
  939.             The x and y coordinate  numbers  in  the  logical coordinate
  940.        space must be in the range of -32768 to +32767.
  941.  
  942.        
  943.        4.3  Related Functions
  944.  
  945.             There are two functions for the  control  of  the coordinate
  946.        system. They are:
  947.             
  948.             SetOrg(x,y) Set the point (x,y) in the physical coordinate
  949.                         system as the origin in the logical coordinate
  950.                         system.
  951.             
  952.             RelOrg(x,y) Set the point (x,y) in the logical coordinate 
  953.                         system as the new origin in the logical 
  954.                         coordinate system.
  955.  
  956.        
  957.  
  958.  
  959.  
  960.                                      - 11 -
  961.  
  962.  
  963.  
  964.        GRAD User's Manual                                    June 7, 1987
  965.  
  966.        4.3.1  SetOrg
  967.  
  968.                SetOrg(x,y);
  969.                int x,y;
  970.  
  971.        a. If you consider the logical coordinate system as  described in
  972.           4.2.1,  to set (x,y) as the origin, the function call required
  973.           is:
  974.                SetOrg(x,y);
  975.  
  976.        b. If you consider the logical coordinate system  as described in
  977.           4.2.2,  to set a and b pixels of  translation in x  and y axes
  978.           will require the function call:
  979.                SetOrg(a,b);
  980.  
  981.        c. If you consider the logical coordinate  system as described in
  982.           4.2.3 and you want to place the upper left corner of the frame
  983.           at (u,v) of the logical space, the function call required is:
  984.                SetOrg(-u,-v);
  985.  
  986.        FUNCTIONS INCLUDED
  987.  
  988.                RelOrg, SetWin, ResetWin
  989.  
  990.        
  991.        4.3.2  RelOrg
  992.  
  993.             The function of RelOrg is exactly the same  as SetOrg except
  994.        the parameter specified is add to the existing setting instead of
  995.        replacing the settings.
  996.  
  997.        
  998.        4.4  Summary
  999.  
  1000.             All coordinate  number  described in  this  manual except in
  1001.        this chapter  are  logical  coordinate  numbers  unless otherwise
  1002.        specified. Initially, the physical and logical coordinate numbers
  1003.        are the  same.  If you do not change it  by one  of the functions
  1004.        SetOrg and RelOrg, they are equivalent.
  1005.             
  1006.             The x coordinate number increase as it move to the right and
  1007.        the y  coordinate number increase  as it move  downwards. The top
  1008.        left corner  of  a frame is  the  origin  (0,0)  of  the physical
  1009.        coordinate system.
  1010.             
  1011.             
  1012.             
  1013.             
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.                                      - 12 -
  1026.  
  1027.  
  1028.  
  1029.        GRAD User's Manual                                    June 7, 1987
  1030.  
  1031.        5   Setting Window
  1032.  
  1033.             Windowing is one of the most important  features provided in
  1034.        GRAD.  Every function described  in this manual  which may change
  1035.        the  frame in  any way is  affected  by the  window setting. Only
  1036.        those  changes which are inside  the  window  are  permitted. Any
  1037.        attempt to change any pixels outside the window are ignored.
  1038.             
  1039.             The pixels outside the window  are essentially  frozen. They
  1040.        are unable to change the state until they are un-frozen.
  1041.             
  1042.             Therefore it is easy to create several windows in  the frame
  1043.        which  are  logically  separated  from  each  others. Furthermore
  1044.        additional  routines  are provided  to facilitate the  writing of
  1045.        application which need to maintain several window in the frame.
  1046.             
  1047.             A  simple  example of  creating and  maintaining windows are
  1048.        included later in this chapter.
  1049.             
  1050.             Only 2  functions in GRAD are directly related  to windowing
  1051.        (but most functions in GRAD are indirectly  related to  it). They
  1052.        are:
  1053.                
  1054.                ResetWin        Reset the window size to frame size
  1055.                SetWin          Set the window to the desired size
  1056.  
  1057.        
  1058.        5.1  Function Description
  1059.  
  1060.        5.1.1  ResetWin
  1061.  
  1062.                ResetWin()
  1063.  
  1064.        RETURN VALUE
  1065.             none
  1066.             
  1067.        DESCRIPTION
  1068.             
  1069.             Reset the window size to the current frame size.
  1070.             
  1071.        EXAMPLE
  1072.  
  1073.                ResetWin();
  1074.  
  1075.        FUNCTIONS INCLUDED
  1076.             SetWin, SetOrg, RelOrg
  1077.  
  1078.        
  1079.        5.1.2  SetWin
  1080.  
  1081.                SetWin(x1,y1,x2,y2);
  1082.                int x1,y2,x2,y2;
  1083.  
  1084.        RETURN VALUE
  1085.             none
  1086.             
  1087.        DESCRIPTION
  1088.             
  1089.  
  1090.                                      - 13 -
  1091.  
  1092.  
  1093.  
  1094.        GRAD User's Manual                                    June 7, 1987
  1095.  
  1096.             A window must be rectangular  in shape.  (x1,y1) and (x2,y2)
  1097.        are coordinates of the opposite corners of the  window. The order
  1098.        is not  important.  Both (x1,y1)  and (x2,y2) are included in the
  1099.        window.
  1100.             
  1101.             If (x1,y1)  and/or (x2,y2)  is/are  outside  the  frame, the
  1102.        window set will be the area of the window within the frame.
  1103.             
  1104.        EXAMPLE
  1105.  
  1106.                SetWin(100,100,200,200);
  1107.  
  1108.             The width and height of the window are both 101 pixels.
  1109.             
  1110.        FUNCTIONS INCLUDED
  1111.             ResetWin, RelOrg, SetOrg
  1112.  
  1113.        
  1114.        5.2  Example
  1115.  
  1116.        /* Below is code segment in C demostrating the use of window. */
  1117.        /* Some of the functions are not yet discussed. So you may    */
  1118.        /* wish to skip this section for the first reading.           */
  1119.  
  1120.        ResetWin();
  1121.        PlotType(1);
  1122.        HorzLine(-10000,-10000,20000,20000);  /* Clear Frame */
  1123.        PlotType(0);    /* select OR type */
  1124.        SetOrg(99,19);  
  1125.        Rectangle(0,0,203,103); /* A rectangle enclosing the window */
  1126.        RelOrg(1,1);    /* top-left-hand corner of the window */
  1127.        SetWin(0,0,200,100);    /* set window */
  1128.        window1=EnvSave(0);     /* save all the environment setting */
  1129.        SetOrg(400,20);         /* move to the second window */
  1130.        SetWin(0,0,100,100);    /* set window */
  1131.        HorzLine(0,0,1000,1000); /* Set all the pixels inside window */
  1132.        PlotType(1);            /* select AND type */
  1133.        window2=EnvSave(0);     /* save all the settings */
  1134.  
  1135.        Circle(50,50,80); /* setting is not affected, draws in window2 */
  1136.        Line(0,0,200,200); 
  1137.        Line(100,0,0,100);
  1138.  
  1139.        EnvRsto(window1,KEEP_SLOT); /* restore environment of window1 */
  1140.        WriteStr(0,LEFT,0,10,
  1141.              "The drawing in this frame is completely unaffected",0,0);
  1142.        WriteStr(0,LEFT,0,20,
  1143.              "By the drawing in the other frame.",0,0);
  1144.  
  1145.        EnvRsto(window2,KEEP_SLOT); /* back to window2 */
  1146.        SolidFill(40,50);
  1147.  
  1148.        EnvRsto(window1,KEEP_SLOT); /* back to window1 */
  1149.        WriteStr(0,LEFT,0,50,
  1150.              "You may switch back and forth between the 2 window",0,0);
  1151.  
  1152.        
  1153.  
  1154.  
  1155.                                      - 14 -
  1156.  
  1157.  
  1158.  
  1159.        GRAD User's Manual                                    June 7, 1987
  1160.  
  1161.        6   GRAD Environment
  1162.  
  1163.             Several parameters of GRAD has global effect.  For examples,
  1164.        plot type,  frame  number,  window setting,  ...et  cetera. These
  1165.        settings are called the environment of GRAD.
  1166.             
  1167.             Sometimes,  one  may wish  to  save  the current environment
  1168.        settings and restore it later. For instances when several windows
  1169.        are using at the same time.
  1170.             
  1171.             GRAD  provides  two  functions  to  save  and  restore these
  1172.        environment settings. You may selectively restore some or all the
  1173.        settings. Those two functions are:
  1174.  
  1175.                EnvSave         Save the current environment
  1176.                EnvRsto         Restore the environment saved
  1177.  
  1178.        
  1179.        6.1  Functions Description
  1180.  
  1181.        6.1.1  EnvSave
  1182.  
  1183.                EnvSave(slot_nu);
  1184.                int slot_nu;
  1185.  
  1186.        RETURN VALUE
  1187.             0  means no more slot  available.  All other positive number
  1188.        means environment is save in the that slot number.
  1189.  
  1190.        DESCRIPTION
  1191.  
  1192.             slot_nu can be from 0 to the maximum slot number. If slot_nu
  1193.        number is 0,  EnvSave will search for an  empty slot.  If none is
  1194.        found,  0 will be returned otherwise the slot number used will be
  1195.        returned.
  1196.             
  1197.             When a slot  number  is  given,  current environment will be
  1198.        saved in  that  slot  number  even  if  that  slot  is used. This
  1199.        provides  a  means  to  dedicate  a  certain  slot  number  for a
  1200.        particular application.  Contents can be changed without worrying
  1201.        about any change of slot number.
  1202.             
  1203.             The following settings  are save  by  EnvSave: frame number,
  1204.        window coordinates, origin, plot type, style and font number.
  1205.             
  1206.             EnvSave will not change any of the settings.
  1207.             
  1208.        Note : When you change active frame,  both the  origin and window
  1209.               setting are saved.  When  the frame  is  re-selected, they
  1210.               will be restored. See also SelectFrame
  1211.  
  1212.        EXAMPLES
  1213.                EnvSave(0);
  1214.  
  1215.             Save the current environment in the next unused slot.
  1216.  
  1217.        FUNCTIONS INCLUDED
  1218.             EnvRsto
  1219.  
  1220.                                      - 15 -
  1221.  
  1222.  
  1223.  
  1224.        GRAD User's Manual                                    June 7, 1987
  1225.  
  1226.        6.1.2  EnvRsto
  1227.  
  1228.                EnvRsto(slot_nu, options);
  1229.                int slot_nu, options;
  1230.  
  1231.        RETURN VALUE
  1232.             none
  1233.  
  1234.        DESCRIPTION
  1235.  
  1236.             EnvRsto will  restore all  or  partial  environment settings
  1237.        saved in the slot.  The slot number should be a value returned by
  1238.        EnvSave.  However,  slot number  0  has special meaning.  If 0 is
  1239.        given,  the environment settings at the time when  the program is
  1240.        first started are restored.
  1241.             
  1242.             The default options are to restore all  settings and release
  1243.        the  slot.  You  may change  the default by  using  the following
  1244.        options.  (The definition of the option can be found in  the file
  1245.        GRADENV.H)
  1246.          
  1247.          KEEP_SLOT     do not release the slot
  1248.          KEEP_WIN      keep the current window setting
  1249.          KEEP_ORG      keep the current origin
  1250.          KEEP_STYLE    keep the current plot style
  1251.          KEEP_PLOTTYPE keep the current plot type
  1252.          KEEP_FRAME    keep the current active frame
  1253.          KEEP_FONT     keep the current font
  1254.          
  1255.             To combine more than 1 options, use bitwise OR operator '|'.
  1256.  
  1257.        EXAMPLE
  1258.                EnvRsto(0);
  1259.  
  1260.             Restore all default settings.
  1261.             
  1262.        FUNCTIONS INCLUDED
  1263.             EnvSave
  1264.  
  1265.        
  1266.        7   Selection of Plot Type
  1267.  
  1268.             Each pixel in the frame must be in one of the two  states --
  1269.        either set or reset. When GRAD draws in the frame, it can force a
  1270.        pixel to set or reset or reverse the state.  In GRAD terminology,
  1271.        the three types of operations are  called OR,  AND and XOR. Their
  1272.        function codes are 0, 1 and 2 respectively.
  1273.             
  1274.           Code    Type         Description
  1275.            0       OR          Force a pixel to set state
  1276.            1       AND         Force a pixel to reset state
  1277.            2       XOR         Reverse the state of a pixel
  1278.           
  1279.           
  1280.             Every GRAD function which draws to the frame  is affected by
  1281.        the current plot type.  The default plot type is OR.  The name of
  1282.        the function to  change the plot type  is PlotType which  will be
  1283.        described in next section.
  1284.  
  1285.                                      - 16 -
  1286.  
  1287.  
  1288.  
  1289.        GRAD User's Manual                                    June 7, 1987
  1290.  
  1291.        7.1  Related Function
  1292.  
  1293.        7.1.1  PlotType
  1294.  
  1295.                ret=PlotType(type);
  1296.                int ret, type;
  1297.  
  1298.        RETURN VALUE
  1299.             The plot type (between 0 and 3) used before this function is
  1300.        executed.
  1301.             
  1302.        DESCRIPTION
  1303.             Set the plot type according to the table below:
  1304.             
  1305.           Code    Type         Description
  1306.            0       OR          Force a pixel to set state
  1307.            1       AND         Force a pixel to reset state
  1308.            2       XOR         Reverse the state of a pixel
  1309.            3       OR          same as type 0
  1310.             
  1311.             If the type specified is greater than  3,  then it will take
  1312.        module 4 of the value given and set according to the table above.
  1313.             
  1314.        EXAMPLE
  1315.  
  1316.                PlotType(0);
  1317.  
  1318.        FUNCTIONS INCLUDED
  1319.  
  1320.                none
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.                                      - 17 -
  1351.  
  1352.  
  1353.  
  1354.        GRAD User's Manual                                    June 7, 1987
  1355.  
  1356.        8   Dot Plotting and Line Drawing
  1357.  
  1358.             This chapter will describe the following functions:
  1359.             
  1360.             Dot(x,y)
  1361.                Plot a single dot
  1362.             
  1363.             SetStyle(style)
  1364.                Set the line style
  1365.             
  1366.             HorzLine(x,y,length,width)
  1367.                Draws  a  horizontal  line  starting  from  (x,y)  in the
  1368.                direction of increasing x.  The width of the  line extend
  1369.                in the direction of increasing y.
  1370.                
  1371.             VertLine(x,y,length,width)
  1372.                Draws  a  vertical  line  starting  from   (x,y)  in  the
  1373.                direction of increasing y.  The width of  the line extend
  1374.                in the direction of increasing x.
  1375.  
  1376.        
  1377.        8.1  Functions Description
  1378.  
  1379.        8.1.1  Dot
  1380.  
  1381.                Dot(x,y);
  1382.                int x,y;
  1383.  
  1384.        RETURN VALUE
  1385.             none
  1386.  
  1387.        DESCRIPTION
  1388.             It plot a dot at location (x,y) of current active frame.
  1389.  
  1390.        EXAMPLE
  1391.  
  1392.                Dot(10,10)
  1393.  
  1394.        FUNCTIONS INCLUDED
  1395.  
  1396.             HorzLine, VertLine
  1397.  
  1398.        
  1399.        8.1.2  SetStyle
  1400.  
  1401.                old=SetStyle(style);
  1402.                unsigned int style, old;
  1403.  
  1404.        RETURN VALUE
  1405.             return the old style setting
  1406.             
  1407.        DESCRIPTION
  1408.             
  1409.             It sets the style of the line  drawn by  HorzLine, VertLine,
  1410.        Line,  Arc1,  Arc2,  Earc1  and Earc2.  Style is  a 16-bit value.
  1411.        Default is  0xffff.  That means the lines drawn  are  solid line.
  1412.        When you call SetStyle,  it just move the value  of the parameter
  1413.  
  1414.  
  1415.                                      - 18 -
  1416.  
  1417.  
  1418.  
  1419.        GRAD User's Manual                                    June 7, 1987
  1420.  
  1421.        to a internal variable except when the value is 0.  In that case,
  1422.        the  original  value will  be  inverted.  (i.e. exclusive or with
  1423.        0xffff).
  1424.             
  1425.        EXAMPLES
  1426.                oldstyle=SetStyle(0xffff);      /* save original style */
  1427.                HorzLine(0,0,100,1);
  1428.                SetStyle(0x3333);
  1429.                HorzLine(0,10,100,1);
  1430.                SetStyle(0);
  1431.                HorzLine(0,20,100,1);
  1432.                SetStyle(0x11ff);
  1433.                HorzLine(0,30,100,1);
  1434.                SetStyle(oldstyle);     /* restore original style */
  1435.             
  1436.             
  1437.             The first line is a solid line. The second and third example
  1438.        draw 2  dotted lines with 2 dots in every 4 dot position. However
  1439.        the ink dots position are complementary of each other. The fourth
  1440.        example draw a mixed of dotted and dashed line.
  1441.             
  1442.        FUNCTIONS INCLUDED
  1443.  
  1444.                none
  1445.  
  1446.        
  1447.        8.1.3  HorzLine
  1448.  
  1449.                HorzLine(x,y,length,width);
  1450.                int x,y,length,width;
  1451.  
  1452.        RETURN VALUE
  1453.             none
  1454.  
  1455.        DESCRIPTION
  1456.             It  draws  a  horizontal  line  (i.e.  parallel  to  x axis)
  1457.        starting from  the point (x,y)  in the increasing  direction of x
  1458.        coordinate. If the length or width is less than or equal to zero,
  1459.        nothing will be drawn.  The width of the line will extend  in the
  1460.        increasing direction of y coordinate.  The line drawn is affected
  1461.        by the style set by SetStyle.
  1462.             
  1463.        EXAMPLE
  1464.                HorzLine(100,100,100,2);
  1465.             
  1466.             Draws a line of length 100 pixels and width is 2. That means
  1467.        a total of 200 pixels are drawn.
  1468.             
  1469.        FUNCTIONS INCLUDED
  1470.                Dot, VertLine
  1471.  
  1472.        
  1473.        8.1.4  VertLine
  1474.  
  1475.                VertLine(x,y,length,width);
  1476.                int x,y,length,width;
  1477.  
  1478.        RETURN VALUE
  1479.  
  1480.                                      - 19 -
  1481.  
  1482.  
  1483.  
  1484.        GRAD User's Manual                                    June 7, 1987
  1485.  
  1486.             none
  1487.  
  1488.        DESCRIPTION
  1489.             It draws a vertical line (i.e.  parallel to y axis) starting
  1490.        from the point (x,y) in the increasing direction of y coordinate.
  1491.        If the length  or  width is less than  or equal  to zero, nothing
  1492.        will be drawn.  The width of the line  extends in  the increasing
  1493.        direction  of  x coordinate.  The  line drawn is affected  by the
  1494.        STYLE set by SetStyle.
  1495.             
  1496.        EXAMPLE
  1497.                VertLine(100,100,100,2);
  1498.             
  1499.             Draws a line of length 100 pixels and width is 2. That means
  1500.        a total of 200 pixels are drawn.
  1501.             
  1502.        FUNCTIONS INCLUDED
  1503.                Dot, HorzLine
  1504.  
  1505.        
  1506.  
  1507.        8.2  Efficiency Consideration
  1508.  
  1509.             HorzLine and VertLine never call Dot to draw  line. They use
  1510.        a much faster method to draw line.  Therefore,  it is much longer
  1511.        to plot 100 consecutive dots than draw a 100 pixels long vertical
  1512.        or horizontal line.
  1513.             
  1514.             HorzLine  in general  draws faster than VertLine  in drawing
  1515.        lines with same length and width. Therefore if you want to draw a
  1516.        block with length and width approximately the same,  it is better
  1517.        to use HorzLine. However, if the style setting is not 0xffff, the
  1518.        result by HorzLine and VertLine are different.
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.  
  1527.  
  1528.  
  1529.  
  1530.  
  1531.  
  1532.  
  1533.  
  1534.  
  1535.  
  1536.  
  1537.  
  1538.  
  1539.  
  1540.  
  1541.  
  1542.  
  1543.  
  1544.  
  1545.  
  1546.                                      - 20 -  
  1547.  
  1548.  
  1549.        GRAD User's Manual                                    June 7, 1987
  1550.  
  1551.        9   Circle, Ellipse and Arc
  1552.  
  1553.             GRAD library provides extensive support for drawing circles,
  1554.        ellipses and arcs.
  1555.             
  1556.             The  circle command  in some programs  or libraries actually
  1557.        draws a polygon.  That  may look  like a circle when  the desired
  1558.        circle is small. But when the desired circle is large, the output
  1559.        will not be a circle any more.
  1560.             
  1561.             The circle and ellipse function in GRAD draw  `true' circles
  1562.        and ellipses. What it means is then the circles and ellipses when
  1563.        displayed  or  printed on  a media with  aspect ratio  equal to 1
  1564.        (i.e.  the width and height of a pixel is  equal),  each pixel of
  1565.        the  circles or  ellipses  is  less  than or equal to  half pixel
  1566.        distance from  a real  circle  or  ellipse  with  the  same size.
  1567.        Furthermore,  each pixel will be adjacent to 2  and only 2 pixels
  1568.        of the circle  or ellipse.  So the region enclosed can  be filled
  1569.        using the fill command.
  1570.             
  1571.             The functions that will be described in this chapter are:
  1572.                Circle          Draws a logical circle
  1573.                Ellipse         Draws a logical ellipse
  1574.                FillCircle      Draws a disc
  1575.                FillEllipse     Draws a elliptical disc
  1576.                Arc1            Arc drawing 1
  1577.                Earc1           Elliptical arc drawing 1
  1578.                Arc2            Arc drawing 2
  1579.                Earc2           Elliptical arc drawing 2
  1580.                ArcPoint        Gives the coordinates of 2 end points
  1581.                                of Arc2 or Earc2
  1582.                
  1583.             Since the aspect ratio of  the output  device may  not be 1.
  1584.        The circle drawn by Circle may not look like a  circle on output.
  1585.        If  you want to get `circle'  in  the output,  you should draw an
  1586.        ellipse with  appropriate  ratio of horizontal  and vertical axes
  1587.        specified.  For example,  the width of  a pixel is  twice  of the
  1588.        height of the pixel on a certain output device. In order to get a
  1589.        `circle', the length of the horizontal axis should be half of the
  1590.        vertical axis.
  1591.  
  1592.        
  1593.        9.1  Functions Description
  1594.  
  1595.        9.1.1  Circle
  1596.  
  1597.                Circle(center_x, center_y, radius);
  1598.                int center_x, center_y, radius;
  1599.  
  1600.        RETURN VALUE
  1601.             none
  1602.  
  1603.        DESCRIPTION
  1604.  
  1605.             This function will draw a logical circle.  radius is in term
  1606.        of pixels and must be greater than or equal to 0. The circle draw
  1607.        is  not affected  by the plot style setting.  (See  also Arc1 and
  1608.        Arc2)
  1609.  
  1610.                                      - 21 -
  1611.  
  1612.  
  1613.  
  1614.        GRAD User's Manual                                    June 7, 1987
  1615.  
  1616.             
  1617.        EXAMPLE
  1618.  
  1619.                Circle(100,100,20);
  1620.  
  1621.             Assume the window is larger than  the circle.  Then the left
  1622.        most,  right most,  top and bottom points  of the  circle will be
  1623.        (80,100), (120,100), (100,80) and (100,120) respectively.
  1624.  
  1625.        FUNCTIONS INCLUDED
  1626.             Arc1
  1627.  
  1628.        
  1629.        9.1.2  Ellipse
  1630.  
  1631.                Ellipse(center_x, center_y, horiz_axis, vert_axis);
  1632.                int center_x, center_y, horiz_axis, vert_axis;
  1633.  
  1634.        RETURN VALUE
  1635.             none
  1636.  
  1637.        DESCRIPTION
  1638.  
  1639.             This  function  will  draw  an  ellipse.  horiz_axis  is the
  1640.        distance in pixel from the center to the left most or  right most
  1641.        point of the ellipse.  vert_axis is the distance from  the center
  1642.        to the top or  bottom  point of  the ellipse.  If  horiz_axis and
  1643.        vert_axis is equal,  the result will be the same as  using Circle
  1644.        will radius  set to  either horiz_axis or  vert_axis. The ellipse
  1645.        drawn  is  not affected  by the  plot style.  (See also Earc1 and
  1646.        Earc2)
  1647.             
  1648.        EXAMPLE
  1649.  
  1650.                Ellipse(100,100,40,20);
  1651.  
  1652.        FUNCTIONS INCLUDED
  1653.             Earc1
  1654.  
  1655.        
  1656.  
  1657.        9.1.3  FillCircle
  1658.  
  1659.                FillCircle(center_x, center_y, radius);
  1660.                int center_x, center_y, radius;
  1661.  
  1662.        RETURN VALUE
  1663.             none
  1664.  
  1665.        DESCRIPTION
  1666.  
  1667.             This function is same as Circle except that the circle drawn
  1668.        will be filled.
  1669.             
  1670.        EXAMPLE
  1671.  
  1672.                FillCircle(100,100,20);
  1673.  
  1674.  
  1675.                                      - 22 -
  1676.  
  1677.  
  1678.  
  1679.        GRAD User's Manual                                    June 7, 1987
  1680.  
  1681.             Assume the window is larger than  the circle.  Then the left
  1682.        most,  right most,  top and bottom points  of the  circle will be
  1683.        (80,100), (120,100), (100,80) and (100,120) respectively.
  1684.  
  1685.        FUNCTIONS INCLUDED
  1686.             FillEllipse, HorzLine, VertLine
  1687.  
  1688.        
  1689.        9.1.4  FillEllipse
  1690.  
  1691.                FillEllipse(center_x, center_y, horiz_axis, vert_axis);
  1692.                int center_x, center_y, horiz_axis, vert_axis;
  1693.  
  1694.        RETURN VALUE
  1695.             none
  1696.  
  1697.        DESCRIPTION
  1698.  
  1699.             This function is same as Ellipse except that the output will
  1700.        be an filled ellipse.
  1701.             
  1702.        EXAMPLE
  1703.  
  1704.                FillEllipse(100,100,40,20);
  1705.  
  1706.        FUNCTIONS INCLUDED
  1707.                FillCircle, HorzLine, VertLine
  1708.  
  1709.        
  1710.  
  1711.        9.1.5  Arc1
  1712.  
  1713.                Arc1(center_x, center_y, radius, arc_spec);
  1714.                int center_x, center_y, radius, arc_spec;
  1715.  
  1716.        RETURN VALUE
  1717.             none
  1718.  
  1719.        DESCRIPTION
  1720.  
  1721.             In the function Arc1, a circle is divided into 8 equal parts
  1722.        as defined later.  You may select any part or parts of the circle
  1723.        to  draw. Moreover, the arcs drawn are affected by the line style
  1724.        selected. 
  1725.             
  1726.             8   equal  parts  of  the  circle  is  obtained  by  drawing
  1727.        horizontal,  vertical and 2  diagonal lines (slope  is  1 and -1)
  1728.        through the center of the circle.  You specify which part  of the
  1729.        circle is required in the parameter arc_spec.
  1730.             
  1731.             The name  of  the eight parts  are  defined  as  follows (in
  1732.        clockwise direction):
  1733.          
  1734.          UP_RIGHT, RIGHT_UP, RIGHT_DOWN, DOWN_RIGHT, DOWN_LEFT,
  1735.          LEFT_DOWN, LEFT_UP and UP_LEFT.
  1736.  
  1737.        Additional constants defined include:
  1738.          UPPER_HALF    = RIGHT_UP | UP_RIGHT | UP_LEFT | LEFT_UP
  1739.  
  1740.                                      - 23 -
  1741.  
  1742.  
  1743.  
  1744.        GRAD User's Manual                                    June 7, 1987
  1745.  
  1746.          LOWER_HALF    = LEFT_DOWN | DOWN_LEFT | DOWN_RIGHT | RIGHT_DOWN
  1747.          LEFT_HALF     = UP_LEFT | LEFT_UP | LEFT_DOWN | DOWN_LEFT
  1748.          RIGHT_HALF    = DOWN_RIGHT | RIGHT_DOWN | RIGHT_UP | UP_RIGHT
  1749.          
  1750.             These constants can be found in the header file GRADARC.H
  1751.             
  1752.             As mentioned above,  the arc drawn is  affected  by the plot
  1753.        style selected.  Due to the way a circle  is drawn,  the style of
  1754.        the arc may not be  uniform.  The result  would be  better if the
  1755.        style setting is symmetrical.  (i.e. the bits when read from left
  1756.        to right or right to left are the same)
  1757.  
  1758.        EXAMPLES
  1759.        (1)     Arc1(50,50,30,UPPER_HALF);
  1760.        (2)     SetStyle(0xc3c3);
  1761.                Arc1(100,100,30,UPPER_HALF | LOWER_HALF);
  1762.  
  1763.             First example will draw the upper half  of  the circle only.
  1764.        The   second  example  will   draw  the  whole  circle   but  the
  1765.        circumference is drawn in dotted line style.
  1766.  
  1767.        FUNCTIONS INCLUDED
  1768.             Circle
  1769.  
  1770.        
  1771.        9.1.6  Earc1
  1772.  
  1773.                Earc1(center_x, center_y, horiz_axis, vert_axis,
  1774.                        arc_spec);
  1775.                int center_x, center_y, horiz_axis, vert_axis, arc_spec;
  1776.  
  1777.        RETURN VALUE
  1778.             none
  1779.  
  1780.        DESCRIPTION
  1781.             Earc1  is  very   similar to Arc1.  Earc1  draws a arc of an
  1782.        ellipse instead of  a arc  of  a  circle.  The  ellipse  is still
  1783.        divided into 8 region. The four lines to divide the ellipse are a
  1784.        horizontal line, a vertical line and two lines joining the points
  1785.        which slope of  the tangent is  1  and -1 respectively. Each line
  1786.        must  go  through the center.  If you do  not understand  how the
  1787.        ellipse is divided, just try some experiments.
  1788.             
  1789.             The naming of each  part is exactly the same  as  Arc1. They
  1790.        are:
  1791.          UP_RIGHT, RIGHT_UP, RIGHT_DOWN, DOWN_RIGHT, DOWN_LEFT,
  1792.          LEFT_DOWN, LEFT_UP and UP_LEFT.
  1793.  
  1794.        Additional constants defined include:
  1795.          UPPER_HALF    = RIGHT_UP | UP_RIGHT | UP_LEFT | LEFT_UP
  1796.          LOWER_HALF    = LEFT_DOWN | DOWN_LEFT | DOWN_RIGHT | RIGHT_DOWN
  1797.          LEFT_HALF     = UP_LEFT | LEFT_UP | LEFT_DOWN | DOWN_LEFT
  1798.          RIGHT_HALF    = DOWN_RIGHT | RIGHT_DOWN | RIGHT_UP | UP_RIGHT
  1799.          
  1800.             These constants can be found in the header file GRADARC.H
  1801.             
  1802.  
  1803.  
  1804.  
  1805.                                      - 24 -
  1806.  
  1807.  
  1808.  
  1809.        GRAD User's Manual                                    June 7, 1987
  1810.  
  1811.             The arcs drawn are affected by the plot style  selected. Due
  1812.        to the way an ellipse is drawn,  the style of the arc  may not be
  1813.        uniform.  The  result  would be  better  if the  style setting is
  1814.        symmetrical. (i.e. the bits when read from left to right or right
  1815.        to left are the same)
  1816.  
  1817.        EXAMPLES
  1818.        (1)     Earc1(50,50,30,60,UPPER_HALF);
  1819.        (2)     SetStyle(0xc3c3);
  1820.                Earc1(100,100,30,60,UPPER_HALF | LOWER_HALF);
  1821.  
  1822.             First example will draw the upper half of  the ellipse only.
  1823.        The  second  example  will   draw  the  whole  ellipse   but  the
  1824.        circumference is drawn in dotted line style.
  1825.             
  1826.        FUNCTIONS INCLUDED
  1827.             Ellipse
  1828.  
  1829.        
  1830.  
  1831.        9.1.7  Arc2
  1832.  
  1833.                Arc2(center_x, center_y, radius,
  1834.                         start_degree, degrees);
  1835.                int center_x, center_y, radius, start_degree, degrees;
  1836.  
  1837.        RETURN VALUE
  1838.             none
  1839.             
  1840.        DESCRIPTION
  1841.  
  1842.             This function draws a circular arc.  The angle of the arc is
  1843.        specified  in  terms of  degrees.  In order words,  the circle is
  1844.        divided  into 360  equal divisions.  You specify the starting and
  1845.        ending division to be drawn.
  1846.             
  1847.             The parameter  start_degree  can  be  any  value  within the
  1848.        allowable range of an integer.  Arc2 will take the positive value
  1849.        of start_degree mod 360 ( start_degree % 360 ).
  1850.             
  1851.             The parameter degrees can be  any values too.  However if it
  1852.        is larger than 360, it is set to 360. If it is less than or equal
  1853.        to zero, nothing will be drawn.
  1854.             
  1855.             The vertically  upward  direction is  considered  to  be the
  1856.        reference line. start_degree is the angle of the line joining the
  1857.        starting point of  the arc  and  center  and  the  reference line
  1858.        measured in clockwise direction. degrees is the angle between the
  1859.        lines joining the starting and ending points to the center.
  1860.             
  1861.             Immediately  after  execution  of  Arc2,  you  can  get  the
  1862.        coordinates  of  the starting  and  ending  points  by  using the
  1863.        function ArcPoint. See the description later in this chapter.
  1864.             
  1865.        EXAMPLES
  1866.        (1)     Arc2(100,100,50,270,180);
  1867.        (2)     Arc2(200,100,50,90,180);
  1868.  
  1869.  
  1870.                                      - 25 -
  1871.  
  1872.  
  1873.  
  1874.        GRAD User's Manual                                    June 7, 1987
  1875.  
  1876.             Example 1  draws the upper half of a circle. Example 2 draws
  1877.        the lower half of a circle.
  1878.             
  1879.        FUNCTIONS INCLUDED
  1880.             Arc1, Circle
  1881.  
  1882.        
  1883.  
  1884.        9.1.8  Earc2
  1885.  
  1886.                Earc2(center_x, center_y, horiz_axis, vert_axis,
  1887.                        start_degree, degrees);
  1888.                int center_x, center_y, horiz_axis, vert_axis;
  1889.                int start_degree, degrees;
  1890.  
  1891.        RETURN VALUE
  1892.             none
  1893.  
  1894.        DESCRIPTION
  1895.             Earc2  is  very  similar to  Arc2.  It draws elliptical arcs
  1896.        instead of  circular  arc.  The angle of the arc  is specified in
  1897.        terms of degrees. In order words, the ellipse is divided into 360
  1898.        divisions.  (note I do not  say equal division.)  You specify the
  1899.        starting and ending division to be drawn.
  1900.             
  1901.             The parameter  start_degree  can  be  any  value  within the
  1902.        allowable range of an integer.  Arc2 will take the positive value
  1903.        of start_degree mod 360 ( start_degree % 360 ).
  1904.             
  1905.             The parameter degrees can be  any values too.  However if it
  1906.        is larger than 360, it is set to 360. If it is less than or equal
  1907.        to zero, nothing will be drawn.
  1908.             
  1909.             The  vertically  upward  direction is  considered  to be the
  1910.        reference line.  Due to the limitation of the algorithm used, all
  1911.        angles are measured on a  output device with  aspect ratio (width
  1912.        of a pixel : height of a pixel) equal to vert_axis/horiz_axis. In
  1913.        other words, the ellipse appear as a `circle'.
  1914.             
  1915.             start_degree is the angle of  the line  joining the starting
  1916.        point of the arc and center  and the reference  line  measured in
  1917.        clockwise  direction.  degrees is  the  angle  between  the lines
  1918.        joining the starting and ending points to the center.
  1919.             
  1920.             Immediately  after  execution  of  Earc2,  you  can  get the
  1921.        coordinates  of  the starting  and  ending  points  by  using the
  1922.        function ArcPoint. See the description later in this chapter.
  1923.             
  1924.        EXAMPLES
  1925.        (1)     Earc2(100,100,60,30,270,180);
  1926.        (2)     Earc2(200,200,60,30,90,180);
  1927.  
  1928.             First  example draws the upper half  of  an  ellipse. Second
  1929.        example draws the lower half of an ellipse.
  1930.             
  1931.        FUNCTIONS INCLUDED
  1932.             Ellipse, Earc1
  1933.  
  1934.  
  1935.                                      - 26 -
  1936.  
  1937.  
  1938.  
  1939.        GRAD User's Manual                                    June 7, 1987
  1940.  
  1941.        9.1.9  ArcPoint
  1942.  
  1943.                ArcPoint(start_x, start_y, end_x, end_y);
  1944.                int *start_x, *start_y, *end_x, *end_y;
  1945.  
  1946.        RETURN VALUE
  1947.             none
  1948.             
  1949.        DESCRIPTION
  1950.             Using this function is only meaningful immediately after the
  1951.        execution of Arc2  or Earc2. If these are any other GRAD function
  1952.        calls in between, the values return may be incorrect.
  1953.             
  1954.             The return values are  stored in the four  parameters given.
  1955.        They  are the (logical)  coordinates  of the  starting and ending
  1956.        points  of  the arc just  drawn  without  considering  the window
  1957.        setting. That means if part of the arc is outside the window, the
  1958.        values  returned  is exactly the  same when the window  is larger
  1959.        than the arc.
  1960.             
  1961.        EXAMPLE
  1962.                Arc1(100,100,50,10,30);
  1963.                ArcPoint(&sx, &sy, &ex, &ey);
  1964.                Line(sx, sy, 100, 100); /* join the starting and ending
  1965.                Line(ex, ey, 100, 100);    point to the center         */
  1966.  
  1967.             A sector is drawn.
  1968.  
  1969.        FUNCTIONS INCLUDED
  1970.             none
  1971.  
  1972.        
  1973.        9.2  Hints
  1974.  
  1975.             Circle,  Arc1  and Arc2  are special cases of Ellipse, Earc1
  1976.        and Earc2.  They are provided because drawing circles are several
  1977.        times faster than drawing ellipse. If in one of your program, you
  1978.        use ellipse  most of the time  and only  requires drawing circles
  1979.        several times,  then you may use ellipse to  draw circles instead
  1980.        in order to reduce program size.
  1981.             
  1982.             Similarly,  Arc1  and Earc1  work faster than Arc2 and Earc2
  1983.        respectively. Use Arc1 and Earc1 whenever possible.
  1984.             
  1985.             ArcPoint is used with Arc2 and Earc2 only. It cannot be used
  1986.        with Arc1 and Earc1.
  1987.             
  1988.             Besides using Arc1,  Arc2, Earc1 and Earc2 to draw arcs, you
  1989.        can also use Circle and Ellipse to draw arcs. The technique is to
  1990.        define a window less than the complete circle or ellipse. So only
  1991.        part of the circle or ellipse is visible. This is useful when you
  1992.        do not need to draw an arc of exactly how many degrees. 
  1993.             
  1994.             Sometimes,  you may want  to draw a circle  or  a sector and
  1995.        then divided that into several smaller sector.  You may draw each
  1996.        small sectors individually but a better techniques is to draw the
  1997.        largest sector after combining the small ones then draw  lines to
  1998.        divided that.  In order to find the points on  the circumference,
  1999.  
  2000.                                      - 27 -
  2001.  
  2002.  
  2003.  
  2004.        GRAD User's Manual                                    June 7, 1987
  2005.  
  2006.        you  should first  define the window equal to  the center  of the
  2007.        circle (or ellipse).  Since  the window  only  include the center
  2008.        point,  the arc is not actually drawn  but the end points  of the
  2009.        arc are stilled calculated. See the example in GRADEGS.GCM.
  2010.             
  2011.             When you want to  know the end  points of a arc  but without
  2012.        actually drawing it out,  you must not define  the window outside
  2013.        the circle because Circle is clever enough not to draw it  but it
  2014.        is not clever to skip the drawing if the window  is  equal to the
  2015.        center point.
  2016.  
  2017.  
  2018.  
  2019.  
  2020.  
  2021.  
  2022.  
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.  
  2055.  
  2056.  
  2057.  
  2058.  
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.  
  2065.                                      - 28 -
  2066.  
  2067.  
  2068.  
  2069.        GRAD User's Manual                                    June 7, 1987
  2070.  
  2071.        10  4-connected Region Filling
  2072.  
  2073.             Region  filling  functions  are  very  useful  and powerful.
  2074.        However, you must be very careful when using them because if your
  2075.        area you wished  to  fill is not enclosed  by  a proper boundary,
  2076.        then the `paint' will leaks out may make your frame very `dirty'.
  2077.             
  2078.             The region filling functions in GRAD will fill a 4-connected
  2079.        region. The definition of a 4-connected region is:
  2080.             
  2081.             All pixels in a 4-connected region  can be  reached one from
  2082.             the other by a sequence of any of the four  one-pixel moves:
  2083.             up,   down,  left,  right,  without  crossing  any  boundary
  2084.             pixel(s).
  2085.             
  2086.        A boundary pixel is defined by its state (either  set  or reset).
  2087.        The state for boundary pixels depends  on the plot type  using at
  2088.        that  time.   It  will  be  explained  later  in   the  functions
  2089.        description.
  2090.  
  2091.             To  fill  a  4-connected  region,   you  need  to  give  the
  2092.        coordinates of  any one  point  in  the  region,  regions filling
  2093.        functions will look for every pixels in the region by themselves.
  2094.        Using any point in  the region  as the starting point  would give
  2095.        the same  result.  (Remark:  but the speed of filling may  have a
  2096.        slight  difference.  Furthermore,  in  current  implementation of
  2097.        PatternFill,  this statement is not completely  true.  It will be
  2098.        explained later when the function is described.)
  2099.             
  2100.             All pixels  outside the window  defined are consider  in the
  2101.        state  same  as the boundary pixels.  In other words,  no `paint'
  2102.        will be painted outside the window.  That means when you may fill
  2103.        a completely  blank frame to a pattern you  want  because maximum
  2104.        window size is the frame size.
  2105.             
  2106.             I try  to give a precise description of  what  the functions
  2107.        will do and will not do in  different situation.  However most of
  2108.        them are common sense.  If you have any problem  in understanding
  2109.        what I said above, try to do some experiments and them come back.
  2110.             
  2111.             The functions that will be described in this chapter are:
  2112.                SolidFill       Set all pixels in the region to the
  2113.                                same state.
  2114.                PatternFill     Fill the region with a user specified
  2115.                                pattern.
  2116.  
  2117.        
  2118.        10.1  Functions Description
  2119.  
  2120.        10.1.1  SolidFill
  2121.  
  2122.                SolidFill(x,y);
  2123.                int x,y;
  2124.  
  2125.        RETURN VALUE
  2126.             none
  2127.             
  2128.        DESCRIPTION
  2129.  
  2130.                                      - 29 -
  2131.  
  2132.  
  2133.  
  2134.        GRAD User's Manual                                    June 7, 1987
  2135.  
  2136.             SolidFill  will  set all pixels  in  the  4-connected region
  2137.        containing (x,y) to the same state. The state depends on the plot
  2138.        type selected at that time.  The boundary pixel state is the same
  2139.        as the state used for filling.  If plot type is 0  (OR type), the
  2140.        region will be set to set state.  If  plot type is  1 (AND type),
  2141.        the region  will be set to  reset state.  If plot type  is 2 (XOR
  2142.        type),  the state used  will depend on  the initial state  of the
  2143.        starting point (x,y).  If it is reset, the region will set to set
  2144.        state, otherwise the region will set to reset state.
  2145.             
  2146.             SolidFill requires  temporary  storage  from  the  stack for
  2147.        working  memory.  The  amount  of memory required  depends on the
  2148.        complexity of  the region.  If you see  the  message  saying that
  2149.        insufficient working memory for filling,  you should increase the
  2150.        stack  size  and try again.  (Look at  your  C compiler reference
  2151.        manual to  see how to  increase  the  stack  size.)  You  are not
  2152.        required to  purposely increase  the stack size  whenever you use
  2153.        fill functions because working storage of 40 bytes are sufficient
  2154.        for most situation.  (Default stack size in most C compiler is at
  2155.        least 2K bytes.)
  2156.             
  2157.        EXAMPLES
  2158.        (1)     PlotType(0);
  2159.                Arc2(100,100,45,150);
  2160.                ArcPoint(&x1, &y1, &x2, &y2);
  2161.                Line(x1,y1,100,100);
  2162.                Line(x2,y2,100,100);
  2163.                SolidFill(100,100);
  2164.        (2)     /* Assume the frame is completely blank at this time */
  2165.                PlotType(2);
  2166.                Circle(100,100,50);
  2167.                SolidFill(100,100);
  2168.                SolidFill(100,100);
  2169.  
  2170.             In the first example,  a sector of 150  degree is filled. In
  2171.        the second  example,  you will  see the  circle  filled  and then
  2172.        erased. Read the description above for explanation.
  2173.             
  2174.        FUNCTIONS INCLUDE
  2175.             PatternFill
  2176.  
  2177.        
  2178.        10.1.2  PatternFill
  2179.  
  2180.                PatternFill(x,y,patptr,0);
  2181.                int x,y,*patptr;
  2182.  
  2183.        RETURN VALUE
  2184.             none
  2185.             
  2186.        DESCRIPTION
  2187.             PatternFill is  very  similar to  SolidFill  except  that it
  2188.        fills  the region  in  user  specified  pattern  and  it  has one
  2189.        limitation in current implementation.
  2190.             
  2191.  
  2192.  
  2193.  
  2194.  
  2195.                                      - 30 -
  2196.  
  2197.  
  2198.  
  2199.        GRAD User's Manual                                    June 7, 1987
  2200.  
  2201.             patptr is a pointer pointing to a integer array of  size 16.
  2202.        The lower order 8 bit will be displayed on the left of the higher
  2203.        order 8  bit.  So you have to swap the lower and  higher  byte in
  2204.        defining your  pattern.  There  is  no  restriction  on  what the
  2205.        pattern should look like. It can be completely set or reset.
  2206.             
  2207.             Owing to some  implementation problems,  the current version
  2208.        of  PatternFill can only  guarantee  filling  of  simple regions.
  2209.        Simple region means the region within the outer boundary does not
  2210.        contain  any  pixel(s)   in  the  same  state  as  the  boundary.
  2211.        Otherwise,  part of the region may not be filled.
  2212.             
  2213.             The actual operation of PatternFill is like  this: The front
  2214.        line  of filling  after the first line  is drawn  will not change
  2215.        direction.  It will continue goes up or down.  Therefore, in some
  2216.        cases,  it can fill area other than simple region. For example, a
  2217.        small rectangle inside a much larger  one and the  starting point
  2218.        is  either  above or below  the small rectangle inside  the large
  2219.        rectangle,  then the whole region will be filled. If the starting
  2220.        point is at the right of the  small rectangle,  the region on the
  2221.        left of the small rectangle will not be filled.
  2222.             
  2223.             Although PatternFill is  not  a  complete  implementation of
  2224.        4-connected region  filling function,  it is  sufficient for most
  2225.        application such as filling pie charts, bar charts etc.
  2226.             
  2227.             The fourth parameter is  not used  in current implementation
  2228.        but it  must be set to  0  in order to be compatible  with future
  2229.        version of PatternFill.
  2230.  
  2231.        EXAMPLE
  2232.                static int pattern[16]={
  2233.                    0x1111, 0x2222, 0x4444, 0x8888,
  2234.                    0x1111, 0x2222, 0x4444, 0x8888,
  2235.                    0x1111, 0x2222, 0x4444, 0x8888,
  2236.                    0x1111, 0x2222, 0x4444, 0x8888 };
  2237.                PlotType(0);
  2238.                Box(100,100,10,50,2,2);
  2239.                PatternFill(105,105,pattern,0);
  2240.  
  2241.             The Box drawn in  the example  will  be  filled  with shaded
  2242.        lines.
  2243.             
  2244.        FUNCTIONS INCLUDED
  2245.             SolidFill
  2246.             
  2247.  
  2248.        
  2249.        10.2  Hints
  2250.  
  2251.  
  2252.  
  2253.  
  2254.  
  2255.  
  2256.  
  2257.  
  2258.  
  2259.  
  2260.                                      - 31 -
  2261.  
  2262.  
  2263.  
  2264.        GRAD User's Manual                                    June 7, 1987
  2265.  
  2266.        11  Text Characters Related Functions
  2267.  
  2268.             A character in GRAD can be completely blank or a block up to
  2269.        about   120   by  120   pixels(can   be   change   easily  during
  2270.        re-comilation).   Font  files  are  loaded  into   memory  during
  2271.        execution time so that you can access  to different  type of font
  2272.        easily.
  2273.             
  2274.             Currently, two types of font files are supported. First type
  2275.        is fixed size font.  Every character in the file  occupy the same
  2276.        space. The second type is variable size font. Some people call it
  2277.        proportional  spacing characters.  The  type of the font  file is
  2278.        transparent to the user except  in some situation when  the exact
  2279.        size and position of  a character or  a string  of characters are
  2280.        important,  then you may need to know whether it is fixed size or
  2281.        variable size. More on this later in this chapter.
  2282.             
  2283.             The functions that will be described in this chapter are:
  2284.                LoadFont    Load a font file into memory.
  2285.                SelectFont  Select the active font type.
  2286.                RemvFont    Remove the font from memory.
  2287.                WriteStr    Write a string of character using the current
  2288.                            font selected.
  2289.                ReadStr     Read a string from keyboard
  2290.                NextXY      get the next coordinates for WriteStr or
  2291.                            ReadStr
  2292.  
  2293.        
  2294.        11.1  Functions Description
  2295.  
  2296.        11.1.1  LoadFont
  2297.  
  2298.                font_number=LoadFont(fontfilename);
  2299.                int font_number;
  2300.                char *fontfilename;
  2301.  
  2302.        RETURN VALUE
  2303.             A font number
  2304.  
  2305.        DESCRIPTION
  2306.             fontfilename is a DOS file name.  When LoadFont is executed,
  2307.        the  whole font file will  be loaded into  memory.  It is kept in
  2308.        memory until it  is  removed by  the  function  call  RemvFont or
  2309.        termination  of  GRAD.  When error occurs,  font number 0 will be
  2310.        returned.  You may  test  for  zero  to  perform  your  own error
  2311.        processing. See also SelectFont.
  2312.  
  2313.        POSSIBLE ERROR CONDITION
  2314.        a. Insufficient Memory
  2315.           font number zero will be returned
  2316.           
  2317.        b. Too Many Fonts Loaded
  2318.           The maximum number of fonts allowed to exist simultaneously is
  2319.           a system parameter.  If the number is exceed, font number zero
  2320.           will be returned.
  2321.           
  2322.        c. File Not File
  2323.  
  2324.  
  2325.                                      - 32 -
  2326.  
  2327.  
  2328.  
  2329.        GRAD User's Manual                                    June 7, 1987
  2330.  
  2331.           The  specified  DOS  file  is  not  found.  Font  number  0 is
  2332.           returned.
  2333.           
  2334.        EXAMPLE
  2335.                font1=LoadFont("E9X14.FON");
  2336.  
  2337.        FUNCTIONS INCLUDED
  2338.             RemvFont
  2339.  
  2340.        
  2341.        11.1.2  SelectFont
  2342.  
  2343.                ret=SelectFont(font_number);
  2344.                int ret, font_number;
  2345.  
  2346.        RETURN VALUE
  2347.             If -1  is returned,  it means the font number given does not
  2348.        exist or the font number is not assigned  to  any font. Otherwise
  2349.        the original font number will be returned.
  2350.  
  2351.        DESCRIPTION
  2352.             It selects the current  active font number.  The font number
  2353.        is obtained  from the  function LoadFont except  font number zero
  2354.        which is predefined as the font in BIOS.  It contains pattern for
  2355.        ASCII character 0  to character 127. It is the default font and a
  2356.        permanent font (means always available) in GRAD.
  2357.  
  2358.        EXAMPLE
  2359.                if ((old_font=SelectFont(font_number)) == (-1))
  2360.                        printf("Font %d does not exist\n",font_number);
  2361.                  .   .   .
  2362.                  .   .   .  use font_number as current font
  2363.                  .   .   .
  2364.                SelectFont(old_font);  /* return to original font */
  2365.  
  2366.        FUNCTIONS INCLUDED
  2367.             SelectFrame
  2368.  
  2369.        
  2370.        11.1.3  RemvFont
  2371.  
  2372.                ret=RemvFont(font_number);
  2373.                int ret, font_number;
  2374.  
  2375.        RETURN VALUE
  2376.             A return  value of  0  means  successful.  -1 means the font
  2377.        number does not exist or the font  number is not assigned  to any
  2378.        font.
  2379.  
  2380.        DESCRIPTION
  2381.             It removes the font from  GRAD and the  memory occupied will
  2382.        be deallocated.
  2383.             
  2384.        EXAMPLE
  2385.                if (RemvFont(font_number)==(-1))
  2386.                        printf("Font %d does not exist\n",font_number);
  2387.  
  2388.        FUNCTIONS INCLUDED
  2389.  
  2390.                                      - 33 -
  2391.  
  2392.  
  2393.  
  2394.        GRAD User's Manual                                    June 7, 1987
  2395.  
  2396.             LoadFont
  2397.  
  2398.        
  2399.        11.1.4  WriteStr
  2400.  
  2401.                WriteStr(options, direction, x, y, string, x_off, y_off);
  2402.                int options, direction, x, y, x_off, y_off;
  2403.                char *string;
  2404.  
  2405.        RETURN VALUE
  2406.             none
  2407.  
  2408.        DESCRIPTION
  2409.             WriteStr is the  most complicated function provided  in GRAD
  2410.        but it is not difficult to use once you understand it. Firstly, I
  2411.        will describe some basic concepts.
  2412.             
  2413.             Each character  in GRAD may be  different size  but they all
  2414.        considered to  be  a rectangular  box,  we called  it a character
  2415.        cell. Size of a character cell is the same for every character in
  2416.        the  fixed size  font file.  But they may be different  for every
  2417.        character in variable size font file.  The width of the character
  2418.        cell  is  called  cell  width and the height  is  called the cell
  2419.        height.  They are parameters  in  the font  file.  Sometimes, the
  2420.        character pattern may be larger  than the character  cell in some
  2421.        special cases but that will be ignored in the time being.
  2422.             
  2423.             There are a total of  seven  parameters  for  WriteStr. They
  2424.        will be described one by one below.  The constants are defined in
  2425.        the include file "GRADIO.H"
  2426.  
  2427.        a. direction  is only  meaningful when AUTO_MOVE options  is used
  2428.           (described  below).  It controls  the direction of  the string
  2429.           printed. Available selections are:
  2430.           LEFT         [default], move left after each character
  2431.           DOWN_LEFT    moves down and left after each character
  2432.           DOWN         moves down after each character
  2433.           DOWN_RIGHT   moves down and right after each character
  2434.           RIGHT        moves right after each character
  2435.           UP_RIGHT     moves up and right after each character
  2436.           UP           moves up after each character
  2437.           UP_LEFT      moves up and left after each character
  2438.           
  2439.        b. options  are divided into 4 sets. They control the referencing
  2440.           point  of  a  character  cell,  clearing  of  character  cell,
  2441.           operation  mode  and  movement  of  text   pointer.  Only  one
  2442.           selection from  each  set can be  used  at  a time. Selections
  2443.           from  different set should  be  combined  using  the  OR ( | )
  2444.           operator. Each set of options will be described separately.
  2445.           
  2446.           A. Referencing  point  options  tells  the  given  point (x,y)
  2447.              located in a character cell. Available selection are:
  2448.              BOTTOM_LEFT   is the default and it  is  most suitable when
  2449.                            direction LEFT is used.
  2450.              BOTTOM_CENTER is most suitable when direction UP or DOWN is
  2451.                            selected.
  2452.              BOTTOM_RIGHT  is  most  suitable  when   direction   UP  is
  2453.                            selected.
  2454.  
  2455.                                      - 34 -
  2456.  
  2457.  
  2458.  
  2459.        GRAD User's Manual                                    June 7, 1987
  2460.  
  2461.              TOP_LEFT      is  most  suitable  when  direction  DOWN  is
  2462.                            selected.
  2463.              TOP_CENTER    is most suitable when direction UP or DOWN is
  2464.                            selected.
  2465.              TOP_RIGHT     is  most  suitable  when  direction  RIGHT is
  2466.                            selected.
  2467.              LEFT_CENTER   is most suitable when direction LEFT or RIGHT
  2468.                            is selected.
  2469.              RIGHT_CENTER  is most suitable when direction LEFT or RIGHT
  2470.                            is selected.
  2471.              
  2472.           B. Clearing  of  Character  Cells.  Although  the  options are
  2473.              provided,  you are not encourage to  use it  and you should
  2474.              avoid  using it  whenever possible.  There are two reasons.
  2475.              First one is the side  effect problem.  Since characters in
  2476.              GRAD may have different sizes. Clearing of a character cell
  2477.              may leave part of  a larger character  under that character
  2478.              cell. Another reason is efficiency problem. If you want the
  2479.              characters  written on a  clear area,  you should clear the
  2480.              whole area  first and then  use  WriteStr  without clearing
  2481.              option. It will be much faster. However, in some situation,
  2482.              use of  this options  is unavoidable so they  are provided.
  2483.              Available selections are:
  2484.              NO_CLEAR      the default.  Do not clear the character cell
  2485.                            before writing.
  2486.              CLEAR_CELL    reset all  the  pixels  within  the character
  2487.                            cell.
  2488.              FILL_CELL     set all the pixels within the character cell.
  2489.              INVERSE_CELL  the effect of this option depends on the plot
  2490.                            type being used.  If plot type 0 is used, the
  2491.                            character cell will be cleared.  If plot type
  2492.                            1 is used, the character cell will be filled.
  2493.                            If  plot type 2  is used,  the character cell
  2494.                            will be inverted.
  2495.           
  2496.           C. Two operation mode is provided. They are:
  2497.              WRITE     the default.  Perform all operations specified in
  2498.                        the other options and then  write  the characters
  2499.                        to the frame.
  2500.              NO_WRITE  Perform  all other operations  specified in other
  2501.                        options but the characters are not written to the
  2502.                        frame.
  2503.              
  2504.           D. Text  pointer movement  options controls the  update of the
  2505.              pointer  after   each  character   is   written.  Available
  2506.              selections are:
  2507.              AUTO_MOVE the default. After writing of character, the text
  2508.                        pointer will be update according to the direction
  2509.                        and  the  cell  height  and  cell  width  of  the
  2510.                        character just written in addition  to the offset
  2511.                        value for x and  y  coordinate  specified  in the
  2512.                        function call.
  2513.              FIX_MOVE  ignore   direction   and   the   character   cell
  2514.                        information.  Update the text pointer  using only
  2515.                        the offset value specified.
  2516.              VAR_MOVE  Update the text pointer using the  user specified
  2517.                        function   in  addition  to   the   offset  value
  2518.                        specified.  This option allows the  user to place
  2519.  
  2520.                                      - 35 -
  2521.  
  2522.  
  2523.  
  2524.        GRAD User's Manual                                    June 7, 1987
  2525.  
  2526.                        the characters wherever he wants. The option will
  2527.                        be  described  in  full  in  the  section  "using
  2528.                        SPACING_FUNC" in the chapter "Advance Topics".
  2529.              
  2530.        c. x and y are the starting coordinates.
  2531.  
  2532.        d. string is a null terminated string which is  printed using the
  2533.           current active font.
  2534.  
  2535.        e. x_off and y_off are the offset  value which will  be  added to
  2536.           the text pointer after each character is written.
  2537.  
  2538.        EXAMPLES
  2539.        1.      WriteStr(0,0,10,100,"This is a test!",0,0);
  2540.        2.      WriteStr(0,0,10,200,"This is a test!",2,0);
  2541.        3.      PlotType(1);
  2542.                WriteStr(TOP_LEFT | SET_CELL,DOWN,10,300,
  2543.                                "This is a test!",0,0);
  2544.  
  2545.             The first example is  the  simplest  form.  It  uses default
  2546.        options.  The second example is the same as the  first one except
  2547.        the spacing between the characters are larger. 2 extra pixels  in
  2548.        the  horizontal  directions are  added to the  text pointer after
  2549.        each  character.  The third  example  will  write  the  string in
  2550.        reverse video from top to down.
  2551.             
  2552.        FUNCTIONS INCLUDED
  2553.             (writec)
  2554.  
  2555.        
  2556.        11.1.5  ReadStr
  2557.  
  2558.                ReadStr(buffer, max_len, startx, starty, mode,
  2559.                                 cursor, end_of_input);
  2560.                char *buffer;
  2561.                int max_len, startx, starty, mode, cursor, end_of_input;
  2562.                
  2563.        RETURN VALUE
  2564.             number of characters entered
  2565.             
  2566.        DESCRIPTION
  2567.             ReadStr reads a line of input from  the keyboard,  echo each
  2568.        character typed and put them into buffer.
  2569.  
  2570.        buffer    is  a character array where the  input  is  stored. The
  2571.                  string  is   null  terminated  and   no  other  control
  2572.                  characters will be stored.
  2573.  
  2574.        max_len   is  the  length  of  the  buffer.   Maximum  number  of
  2575.                  characters can be entered is max_len - 1.
  2576.  
  2577.        startx, starty is  the starting  coordinate  of  the baseline for
  2578.                  echoing the characters entered.
  2579.  
  2580.        mode      controls how the cursor will appear.
  2581.                  NO_CURSOR       no cursor is displayed but the area
  2582.                                  under the cursor is cleared
  2583.                  DISP_CURSOR     just display the cursor
  2584.  
  2585.                                      - 36 -
  2586.  
  2587.  
  2588.  
  2589.        GRAD User's Manual                                    June 7, 1987
  2590.  
  2591.                  BLINK_CURSOR    the cursor character turns on and off
  2592.                  REVERSE_CURSOR  it keeps reversing the cursor
  2593.                  
  2594.                  You may only use one of the above 4 options at a time
  2595.                  but it may combine with the next option.
  2596.                  SHOW_EOI        shows end of input character when
  2597.                                  return is pressed.
  2598.                                  
  2599.        cursor    the character used for cursor
  2600.  
  2601.        end_of_input the character displayed at the end of the line if
  2602.                  SHOW_EOI option is specified in mode.
  2603.  
  2604.             There are  two special key in  ReadStr.  The return key will
  2605.        terminate the input line  and the backspace key  will  delete the
  2606.        last  character typed on  the  line  if  any.  All  other control
  2607.        characters  are ignored.  If  more characters are input  than the
  2608.        buffer can hold, all excess characters will be discarded.
  2609.             
  2610.        EXAMPLE
  2611.                char line[80];
  2612.                ReadStr(line,80,0,100,BLINK_CURSOR | SHOW_EOI, 0x5f, 17);
  2613.  
  2614.             It reads input from  the keyboard  and put  them  into line.
  2615.        Maximum length is 79 characters plus a carriage return.
  2616.  
  2617.        FUNCTIONS INCLUDED
  2618.             writec, WriteStr, HorzLine, PlotType
  2619.  
  2620.        
  2621.        11.1.6  NextXY
  2622.  
  2623.                NextXY(x,y);
  2624.                int *x, *y;
  2625.  
  2626.        RETURN VALUE
  2627.             values  are   returned  in  the   2   parameters.  They  are
  2628.        coordinates for next character in ReadStr and WriteStr.
  2629.             
  2630.        DESCRIPTION
  2631.             NextXY is for ReadStr and WriteStr only. It returns the next
  2632.        coordinate  in  ReadStr  and  WriteStr  if  there   is  any  more
  2633.        characters to  display.  It  should  be  called immediately after
  2634.        ReadStr and WriteStr otherwise the result may be destroyed.
  2635.  
  2636.        EXAMPLE
  2637.                WriteStr(0,0,10,100,"Enter your name : ",0,0);
  2638.                NextXY(&x, &y);
  2639.                ReadStr(line,80,x,y,BLINK_CURSOR,0x5f,0x5f);
  2640.  
  2641.             It print the string "Enter your name : " and then prompt for
  2642.        input immediate after the string.
  2643.  
  2644.        FUNCTIONS INCLUDED
  2645.                none
  2646.  
  2647.  
  2648.  
  2649.  
  2650.                                      - 37 -
  2651.  
  2652.  
  2653.  
  2654.        GRAD User's Manual                                    June 7, 1987
  2655.  
  2656.        12  Block Operations
  2657.  
  2658.             The functions provide ways  to move data  between frames and
  2659.        between frame and external data.  Each block must be a rectangle.
  2660.        When data are  moved to a  GRAD frame,  it can be OR,  AND or XOR
  2661.        with the original data according to the plot type setting.
  2662.             
  2663.             The functions that will be described in this chapter are:
  2664.                BlockCopy       Copy a block between 2 frames
  2665.                BlockSave       Move a block to a disk file
  2666.                BlockLoad       Load a block from a disk file
  2667.  
  2668.        
  2669.        12.1  Function Description
  2670.  
  2671.        12.1.1  BlockCopy
  2672.  
  2673.                ret=BlockCopy(src_frame, src_x, src_y,
  2674.                              dest_frame, dest_x, dest_y,
  2675.                              length, height);
  2676.                int ret, src_frame, src_x, src_y, dest_frame, dest_x;
  2677.                int dest_y, length, height;
  2678.  
  2679.        RETURN VALUE
  2680.             0 means OK. -1 means one of the frame specified is invalid.
  2681.             
  2682.        DESCRIPTION
  2683.  
  2684.             BlockCopy is  used  to  copy  a rectangular  block  from the
  2685.        source frame (src_frame)  to the  destination  frame (dest_frame)
  2686.        specified.  The two frame number can be the same or different but
  2687.        they must  exist at  the time  the call  is  made.  If  the frame
  2688.        numbers are the same,  the source block and the destination block
  2689.        must  not  overlapped  with  each  other  otherwise unpredictable
  2690.        result may be obtained.
  2691.             
  2692.             In  the current implementation,  the  lower 4  bit of dest_x
  2693.        must be  equal to  lower 4  bit of src_x.  If not, BlockCopy will
  2694.        force them to  be equal  by copying the  lower 4  bit of src_x to
  2695.        dest_x.
  2696.             
  2697.             When the block is copied to the destination frame, the block
  2698.        will be OR,  AND or XOR with the original data in the destination
  2699.        block according to the current plot type selected.
  2700.             
  2701.             Both the window setting of the source  and destination frame
  2702.        will affect the size of the block actually copied. BlockCopy will
  2703.        not copy  any data  from  area  outside the window  of the source
  2704.        frame and it will not write to any area outside of  the window of
  2705.        the destination frame.
  2706.             
  2707.             BlockCopy will  not affect  the  current  frame  number. The
  2708.        source and destination frame may be  different  from  the current
  2709.        frame selected.
  2710.             
  2711.        EXAMPLE
  2712.  
  2713.                frame1=CreateFrame(960,480);
  2714.  
  2715.                                      - 38 -
  2716.  
  2717.  
  2718.  
  2719.        GRAD User's Manual                                    June 7, 1987
  2720.  
  2721.                frame2=SelectFrame(frame1);
  2722.                Ellipse(480,240,450,230);
  2723.                BlockCopy(frame1,0,0,frame2,0,0,960,480);
  2724.                
  2725.             Let's assume  the Color Graphics  Adapter display  memory is
  2726.        the original frame selected before execution of the example above
  2727.        and the window size is equal to  frame size.  frame2 will contain
  2728.        the  frame  number  of  the  CGA  frame.  The  length  and height
  2729.        specified in the BlockCopy command is  960  and 480 respectively.
  2730.        However,  the resolution of a CGA is only 640  and 200. Therefore
  2731.        only the upper left corner (640 by 200) of frame1 is copied.
  2732.             
  2733.        FUNCTIONS INCLUDED
  2734.             
  2735.             none
  2736.  
  2737.        
  2738.        12.1.2  BlockSave
  2739.  
  2740.                BlockSave(start_x, start_y, filename, width, height);
  2741.                int start_x, start_y, width, height;
  2742.                char *filename;
  2743.  
  2744.        RETURN VALUE
  2745.             none
  2746.  
  2747.        DESCRIPTION
  2748.             
  2749.             BlockSave will  save  the  block  specified  in  the current
  2750.        active frame to a file with the  given filename.  All data if any
  2751.        in that file will be replaced by the new data.  If that file does
  2752.        not exist, a new file will be created. The coordinates of the top
  2753.        left corner  of  the block is  given by start_x  and start_y. The
  2754.        width and height is specified in the corresponding parameter with
  2755.        the same name.  If the block does  not lay completely  inside the
  2756.        window, only the portion inside the window is saved. If the block
  2757.        is completely outside the window,  no data will be saved  and the
  2758.        file will not be affect if it already exist or the file  will not
  2759.        be created.
  2760.             
  2761.             The actual width and height of  the block will  be stored in
  2762.        the data file also.  The format of the data file is  described in
  2763.        the appendix.
  2764.  
  2765.        EXAMPLE
  2766.  
  2767.                BlockSave(0,0,"test.blk",100,100);
  2768.  
  2769.             Assume the whole block is inside the window,  then the block
  2770.        100 by 100 pixels will be stored in the file "test.blk".
  2771.  
  2772.        FUNCTIONS INCLUDED
  2773.             BlockLoad
  2774.  
  2775.        
  2776.        12.1.3  BlockLoad
  2777.  
  2778.                ret=BlockLoad(start_x, start_y, filename);
  2779.  
  2780.                                      - 39 -
  2781.  
  2782.  
  2783.  
  2784.        GRAD User's Manual                                    June 7, 1987
  2785.  
  2786.                int ret, start_x, start_y;
  2787.                char *filename;
  2788.  
  2789.        RETURN VALUE
  2790.             0  means success. -1 indicates error. It may due to file not
  2791.        found or bad file.
  2792.             
  2793.        DESCRIPTION
  2794.  
  2795.             BlockLoad is the counterpart of BlockSave.  It loads a block
  2796.        file into  the current frame with  the top  left  hand  corner at
  2797.        (start_x,  start_y).  In current implementation, the lower bit of
  2798.        start_x must be equal to the lower 4  bit of the original start_x
  2799.        (in BlockSave)  when  BlockSave is  used.  If not, BlockLoad will
  2800.        force them to match by changing the start_x of BlockLoad.
  2801.             
  2802.             The  way  the  data  is  stored  in  the  current  frame  is
  2803.        controlled by the current plot type. 
  2804.             
  2805.             This is  no  explicit command to load  part of a  block file
  2806.        only.  However,  you may do this by setting the window to exclude
  2807.        part of the block to  be loaded.  No data will  be loaded outside
  2808.        the current window setting.
  2809.             
  2810.        EXAMPLE
  2811.  
  2812.                BlockLoad(400,0,"test.blk");
  2813.  
  2814.        FUNCTIONS INCLUDED
  2815.             BlockSave
  2816.  
  2817.        
  2818.  
  2819.  
  2820.  
  2821.  
  2822.  
  2823.  
  2824.  
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.  
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.  
  2844.  
  2845.                                      - 40 -
  2846.  
  2847.  
  2848.  
  2849.        GRAD User's Manual                                    June 7, 1987
  2850.  
  2851.        13  Frame Printing
  2852.  
  2853.             Before you try to print a frame using the function described
  2854.        in this chapter,  make sure that you have the  correct driver for
  2855.        your printer.  Customizing  of  printer  driver  is  discussed in
  2856.        Appendix A.
  2857.             
  2858.             Since  different   printers  may   use   different  ways  in
  2859.        controlling graphics printing and you may  have different printer
  2860.        driver,  it is impossible to discuss every possible cases. Hence,
  2861.        I would discuss the general situation and use EPSON FX printer as
  2862.        an example.  If you have problem in  understanding,  try to ask a
  2863.        friend who owns  a EPSON FX  or compatible printer to  explain to
  2864.        you.
  2865.             
  2866.             The function that will be explained in this chapter is:
  2867.             
  2868.             PrintFrame
  2869.                Dump the current selected frame to the printer any may
  2870.                overlay with text data.
  2871.  
  2872.             
  2873.             Allowing  the  merge  printing  of  text  and  graphics data
  2874.        greatly  increase  the  speed  of  printing  when  both  text and
  2875.        graphics data are required because  it don't need to  convert the
  2876.        text into graphics data before printing by the program.
  2877.             
  2878.             Use of software printer  spooler can speed up  the printing.
  2879.        Size of the buffer should be 16K bytes or more.
  2880.  
  2881.        
  2882.        13.1  Function Description
  2883.  
  2884.        13.1.1  PrintFrame
  2885.  
  2886.                PrintFrame(options, page, line, line_height, offset);
  2887.                int option, line, line_height, offset;
  2888.                char *page[];
  2889.  
  2890.        RETURN VALUE
  2891.             none
  2892.  
  2893.        DESCRIPTION
  2894.             This function merge print the text data given if any and the
  2895.        current active frame to the printer. The parameters are explained
  2896.        below. The constants can be found in GRADIO.h
  2897.             
  2898.        a. options  consist of  2  sets of  options  for  the  control of
  2899.           vertical  and horizontal  printing  density. Available options
  2900.           depends  on  the printer driver  you have.  The  options given
  2901.           below are for the EPSON FX printer driver.
  2902.           
  2903.           A. Vertical density
  2904.              NORMAL_DOT   The spacing between 2 vertical dot on paper
  2905.                           is equal to the spacing between 2 pins on the
  2906.                           print head in the printer.
  2907.              
  2908.              SMALL_DOT    The spacing between 2 vertical dot is 1/3 of
  2909.  
  2910.                                      - 41 -
  2911.  
  2912.  
  2913.  
  2914.        GRAD User's Manual                                    June 7, 1987
  2915.  
  2916.                           spacing between 2 pins on the print head.
  2917.              
  2918.              I think the best way to explain these is to see an example.
  2919.              The  EPSON FX  printers can print  up to 216  dots per inch
  2920.              vertically.  However, the spacing between pins in the print
  2921.              head is 1/72  inch (3 times of 1/216). In order to print at
  2922.              high  resolution,  the printer spaces 1/216  inch after the
  2923.              first pass  and the  second  pass  and  then  spaces 22/216
  2924.              inches (2/216  +  22/216  =  8/72) and repeat the procedure
  2925.              again.  As a result,  it can print 216  dots vertically per
  2926.              inch.
  2927.              
  2928.              When you specify the SMALL_DOT option, PrintFrame will take
  2929.              advantage of this features and the print the frame  at high
  2930.              resolution. Otherwise, the frame will be printed at 72 dots
  2931.              per inch vertically.
  2932.              
  2933.           B. Horizontal density
  2934.              LOW_DENSITY     The resolution is 60 dots per inch
  2935.              MEDLOW_DENSITY  The resolution is 72 dots per inch
  2936.              MEDIUM_DENSITY  The resolution is 80 dots per inch
  2937.              HIGH_DENSITY    The resolution is 120 dots per inch
  2938.              ULTRA_DENSITY   The resolution is 240 dots per inch
  2939.              
  2940.              Not all EPSON FX  printers  support all of  the above print
  2941.              mode. Read you manual to see which modes are supported.
  2942.              
  2943.        b. page is a pointer to an array of character pointer. PrintFrame
  2944.           gets the text  data using  this pointer.  Also see the example
  2945.           below.
  2946.  
  2947.        c. line is the number of line given in the array pointer by page.
  2948.           If it is zero,  PrintFrame will not look  at page  and no text
  2949.           data overlaid with the frame in printing.
  2950.  
  2951.        d. height  is the number of points between the base  lines of two
  2952.           rows of text data.  A point is defined as the distance between
  2953.           two pins on the print head. For example, the distance two pins
  2954.           on the print head  of  EPSON FX  printer is 1/72  inch. If you
  2955.           want to print at 6  lines per inch,  you should specify 12 (72
  2956.           divided by 6) as height.
  2957.  
  2958.        e. offset  specify  the distance of the first line  of  text data
  2959.           from  the top of  the frame.  offset  is  in term of  point as
  2960.           defined just a second ago. Negative offset means the text data
  2961.           is shifted downward relative to the top of the frame. Positive
  2962.           offset means the text data is shifted upward.
  2963.  
  2964.             
  2965.             The text data and the frame need not be the same  length and
  2966.        width.  However the text data must not longer than 1 line because
  2967.        that will cause auto line feed of the printer and  the  text data
  2968.        must not contain any control codes that will cause  the moving of
  2969.        paper.  There is an exceptional case when the printer is  in near
  2970.        letter quality mode, the printer will automatically line feed for
  2971.        1/216. This is OK.
  2972.             
  2973.        FUNCTIONS INCLUDED
  2974.  
  2975.                                      - 42 -
  2976.  
  2977.  
  2978.  
  2979.        GRAD User's Manual                                    June 7, 1987
  2980.  
  2981.             none
  2982.  
  2983.  
  2984.  
  2985.  
  2986.  
  2987.  
  2988.  
  2989.  
  2990.  
  2991.  
  2992.  
  2993.  
  2994.  
  2995.  
  2996.  
  2997.  
  2998.  
  2999.  
  3000.  
  3001.  
  3002.  
  3003.  
  3004.  
  3005.  
  3006.  
  3007.  
  3008.  
  3009.  
  3010.  
  3011.  
  3012.  
  3013.  
  3014.  
  3015.  
  3016.  
  3017.  
  3018.  
  3019.  
  3020.  
  3021.  
  3022.  
  3023.  
  3024.  
  3025.  
  3026.  
  3027.  
  3028.  
  3029.  
  3030.  
  3031.  
  3032.  
  3033.  
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.                                      - 43 -
  3041.  
  3042.  
  3043.  
  3044.        GRAD User's Manual                                    June 7, 1987
  3045.  
  3046.        14  The DRAW function
  3047.  
  3048.             Draw function provides features similar turtle graphics. The
  3049.        main idea  is  to keep track  of the current coordinates  and use
  3050.        these  coordinate when a function  required  a coordinate number.
  3051.        This help the user to  draw complex figures  without worrying the
  3052.        exact coordinates.
  3053.             
  3054.             The command string for draw  function is very  compact. This
  3055.        also help keeping the program size small.  On the other hand, use
  3056.        of  Draw  functions  will  include  all  GRAD  functions  that is
  3057.        accessible  from Draw at link time even if  you do  not use them.
  3058.        This will increase the executable file size.
  3059.  
  3060.        
  3061.        14.1  Draw
  3062.  
  3063.                Draw(string, parm1, parm2);
  3064.                char *string;
  3065.                int parm1, parm2;
  3066.  
  3067.        RETURN VALUE
  3068.             none
  3069.             
  3070.        DESCRIPTION
  3071.             string is  the  Draw  command  string.  The  syntax  will be
  3072.        described later.  parm1  and parm2 will be assigned to X and Y of
  3073.        marker 0. It will be explained further when we talk about marker.
  3074.        The command string can be any length  but it  has to  be in ASCII
  3075.        and terminated by a NULL character.
  3076.             
  3077.             On entry,  the current environment is saved.  If there is no
  3078.        environment slot  available,  it  is  an  irrecoverable error and
  3079.        program will normally terminated unless a function  is registered
  3080.        for error handling.  On exit,  the  environment  is  not restored
  3081.        automatically.  However,  Draw  provides  an  environment restore
  3082.        command (EO).  You can use it at the end of the command string to
  3083.        restore the environment before exit.
  3084.             
  3085.             The syntax for the command string is given below.
  3086.                :=    stands for define as
  3087.                |     means or
  3088.                [  ]  means this is optional
  3089.                {  }  select one of the entities inside
  3090.          
  3091.          CMD_STRING := CMD_UNITS
  3092.          CMD_UNITS  := CMD_UNIT | CMD_UNIT CMD_UNITS
  3093.          CMD_UNIT   := CMD_CODE[$] [PARAMETERS]
  3094.          CMD_CODE   := LETTER LETTER
  3095.          PARAMETERS := PARAMETER | PARAMETER , PARAMETERS
  3096.          PARAMETER  := DECIMAL | HEXADECIMAL | {&|%}DIGIT{X|Y}
  3097.          DIGIT      := 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
  3098.          DECIMAL    := [+|-]DIGITS
  3099.          DIGITS     := DIGIT | DIGITDIGITS
  3100.          HEXDIGIT   := DIGIT | A | B | C | D | E | F | a | b | c | d
  3101.                            | e | f
  3102.          HEXADECIMAL:= 0XHEXDIGITS | 0xHEXDIGITS
  3103.          HEXDIGITS  := HEXDIGIT | HEXDIGITHEXDIGITS
  3104.  
  3105.                                      - 44 -
  3106.  
  3107.  
  3108.  
  3109.        GRAD User's Manual                                    June 7, 1987
  3110.  
  3111.          LETTER is defined as letter A to Z and a to z
  3112.          
  3113.        If there is  any space separating  any 2  entities  in  the above
  3114.        definition,  it means zero, one or spaces are allowed except when
  3115.        this  is  ambiguity.  For  example,  the  last  parameter  in the
  3116.        preceding CMD_UNIT is  a hexadecimal number.  Since a hexadecimal
  3117.        number may contain a to  f and A to  F which are  also  belong to
  3118.        LETTER.  Therefore it  is necessary  to insert a space  after the
  3119.        last parameter if  that  is  a hexadecimal  number  and  the next
  3120.        CMD_CODE begins with letter a to f or A to F.
  3121.  
  3122.             Below is  a  table  showing  the  command  codes,  number of
  3123.        parameters required,  whether the current coordinates is affected
  3124.        and  a brief description.  P#  (#  represent a digit from 1 to 9)
  3125.        stands for the parameter #.  For example P1  stands for the first
  3126.        parameter.
  3127.  
  3128.        CMD_  no. of  affect
  3129.        CODE  param.  coord.   Description
  3130.        ----  -----   ------   -----------
  3131.         RS     0       No     Reset the window to frame size, logical
  3132.                               origin to physical coordinate 0. The
  3133.                               current coordinates number will change to
  3134.                               reflect the change of the coordinate
  3135.                               system if necessary.
  3136.  
  3137.         LF     1       Yes    move left P1 pixels.
  3138.         RT     1       Yes    move right P1 pixels.
  3139.         UP     1       Yes    move up P1 pixels.
  3140.         DN     1       Yes    move down P1 pixels.
  3141.         UL     1       Yes    move up and left P1 pixels.
  3142.         UR     1       Yes    move up and right P1 pixels.
  3143.         DL     1       Yes    move down and left P1 pixels.
  3144.         DR     1       Yes    move down and right P1 pixels.
  3145.         JR     2       Yes    move left and down P1 and P2 pixels
  3146.                               respectively. P1 and P2 can be negative to
  3147.                               stands for moving right and up.
  3148.         JA     2       Yes    jump to (P1,P2)
  3149.         /* NW and PU only affects the commands */
  3150.         /* LF, RT, UP, DN, UL, UR, DL, DR, JR  */
  3151.                               above                                       
  3152.                               */
  3153.         WR     0       No     write (selects plot type OR)
  3154.         ER     0       No     erase (selects plot type AND)
  3155.         RV     0       No     reverse (selects plot type XOR)
  3156.         NW     0       No     set flag such that when the current
  3157.                               coordinate move, no ink is left on the
  3158.                               frame.
  3159.         PU     0       No     Pen Up for the during next command. The
  3160.                               effect is similar to NW except it only
  3161.                               last for 1 command only.
  3162.         HL     2       Yes    draws a horizontal line starting at
  3163.                               current coordinate and length P1 to the
  3164.                               left and width P2 downward. P1 and P2
  3165.                               cannot be negative.
  3166.  
  3167.  
  3168.  
  3169.  
  3170.                                      - 45 -
  3171.  
  3172.  
  3173.  
  3174.        GRAD User's Manual                                    June 7, 1987
  3175.  
  3176.         VL     2       Yes    draws a vertical line starting at current
  3177.                               coordinates and length P1 downward and
  3178.                               width P2 to the left. P1 and P2 cannot be
  3179.                               negative.
  3180.         SO     0              set the current position as the new
  3181.                               origin. Current coordinates are set to
  3182.                               zero to reflect change of coordinate
  3183.                               system.
  3184.         SY     1       No     set line style to P1
  3185.         AS     1       No     set arc drawing specification for use by
  3186.                               CI (circle) and EL (ellipse).
  3187.         MK     1       No     put current coordinates into marker P1.
  3188.         MK     3       No     put (P2,P3) into marker P1
  3189.         WN     2       No     the 2 corners of the window is the current
  3190.                               location and (P1,P2).
  3191.         DY     1       No     delay for P1/100 seconds. It is not very
  3192.                               accurate.
  3193.         CI     1       No     current coordinates are the center, P1 is
  3194.                               the radius. It also affected by the arc
  3195.                               specification setting.
  3196.         EL     2       No     current coordinates are the center, P1 is
  3197.                               the length of the horizontal axis and P2
  3198.                               is the length of the vertical axis.
  3199.         RE     2       No     draws a rectangle with upper left corner
  3200.                               at current location and width and height
  3201.                               are P1 and P2 respectively.
  3202.         BX     4       No     draws a box with upper left corner at
  3203.                               current location. Width and height are P1
  3204.                               and P2 respectively. P3 and P4 are the
  3205.                               width of the horizontal and vertical lines
  3206.                               of the box.
  3207.         FC     1       No     draws a solid circle with radius P1
  3208.         FE     2       No     draws a solid ellipse with horizontal and
  3209.                               vertical axes equal to P1 and P2
  3210.                               respectively.
  3211.         ES     0       No     environment variables save into the slot
  3212.                               allocated on entry.
  3213.         EO     1              environment restore from the slot using
  3214.                               parameter P1. KEEP_SLOT is implied. It
  3215.                               does not affect the value of current
  3216.                               coordinates but it may affect the location
  3217.                               of the origin and hence affect the actual
  3218.                               location.
  3219.         FI     0       No     Fill the region starting from current
  3220.                               location.
  3221.  
  3222.             Marker is a  unique feature provided by  draw so it  will be
  3223.        discussed in  detail.  Draw process a total of  10  markers. Each
  3224.        marker can store 2  integer values in the registers called  X and
  3225.        Y.  Coordinate numbers are usually  stored but you  may store any
  3226.        integer values in the marker.  Marker 0 is a special marker which
  3227.        initially values in registers X and Y are  the  second  and third
  3228.        parameters given when Draw is called.
  3229.             
  3230.             There are two ways to retrieve a marker. The first way is to
  3231.        retrieve the absolute value of the markers.  It is done by typing
  3232.        %#X or  %#Y (#  stands  for a digit 0..9)  in the  place  where a
  3233.        parameter is expected. The second way is to retrieve the value of
  3234.  
  3235.                                      - 46 -
  3236.  
  3237.  
  3238.  
  3239.        GRAD User's Manual                                    June 7, 1987
  3240.  
  3241.        the marker relative to the  current coordinates.  You can do this
  3242.        by typing &#X or &#Y in the place where a parameter  is expected.
  3243.        When the X part is retrieved,  the return value will  be relative
  3244.        to current X coordinate. Similarly when Y part is retrieved.
  3245.             
  3246.             In  the table given above,  some  functions  when  used will
  3247.        affect  the  current  coordinates.  However,  if  you  add  a '$'
  3248.        immediately after the command code,  then the current coordinates
  3249.        will not  be  affected.  Adding  a  '$'  is  only  meaningful for
  3250.        functions that is stated 'Yes' in the table above.
  3251.             
  3252.        EXAMPLE
  3253.                Draw("NW RT6 AS0xc0 EL5,9 UP9 WR RT228",0,0);
  3254.                Draw("NW DN9 AS0x03 EL5,9 RT5 WR DN304",0,0);
  3255.                Draw("NW LF6 AS0x0c EL5,9 DN9 WR LF228",0,0);
  3256.                Draw("NW UP9 AS0x30 EL5,9 LF5 WR UP304",0,0);
  3257.             
  3258.             The above lines will draw a rectangle with round corner.
  3259.             
  3260.        FUNCTIONS INCLUDED
  3261.             Line,  Plottype,  Dot, HorzLine, VertLine, SetStyle, SetOrg,
  3262.        RelOrg,   SetWin,   Circle,  Arc1,  Ellipse,  Earc1,  FillCircle,
  3263.        FillEllipse, EnvSave, EnvRsto, SolidFill, PatternFill.
  3264.  
  3265.  
  3266.  
  3267.  
  3268.  
  3269.  
  3270.  
  3271.  
  3272.  
  3273.  
  3274.  
  3275.  
  3276.  
  3277.  
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.  
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.  
  3297.  
  3298.  
  3299.  
  3300.                                      - 47 -
  3301.  
  3302.  
  3303.  
  3304.        GRAD User's Manual                                    June 7, 1987
  3305.  
  3306.        15  Miscellaneous Functions
  3307.  
  3308.             This chapter will describe  those functions that  do not fit
  3309.        into any other chapter in this manual. It includes:
  3310.                
  3311.                GRADinit        initialize the GRAD environment
  3312.                cleanup         clean up everything before exit
  3313.                XHLine          extend to left and right from a point
  3314.                writec          write a single character
  3315.  
  3316.        
  3317.        15.1  Functions Description
  3318.  
  3319.        15.1.1  GRADinit
  3320.  
  3321.                GRADinit();
  3322.  
  3323.        RETURN VALUE
  3324.             none
  3325.  
  3326.        DESCRIPTION
  3327.             GRADinit  initialize  the  GRAD  environment  and  test  the
  3328.        processor speed and put the  result  into  TEN_MS.  See  also the
  3329.        description of TEN_MS.  It should be called before using any GRAD
  3330.        functions.  Once GRADinit is called, you must call cleanup before
  3331.        exit. Read the description of cleanup in next section.
  3332.             
  3333.        EXAMPLE
  3334.                GRADinit();
  3335.  
  3336.        FUNCTIONS INCLUDED
  3337.             cleanup
  3338.  
  3339.        
  3340.        15.1.2  cleanup
  3341.  
  3342.                cleanup(exit_code);
  3343.                int exit_code;
  3344.  
  3345.        RETURN VALUE
  3346.             none
  3347.             
  3348.        DESCRIPTION
  3349.             cleanup must  be  called  if  GRADinit  was  called.  If the
  3350.        exit_code is non-zero,  cleanup will terminate the  program after
  3351.        clean up using the exit code.  If exit_code is zero, cleanup will
  3352.        return control to the caller.
  3353.             
  3354.        EXAMPLE
  3355.                cleanup(1);
  3356.  
  3357.             Cleans up and terminate the program.
  3358.             
  3359.        FUNCTIONS INCLUDED
  3360.             GRADinit
  3361.  
  3362.        
  3363.  
  3364.  
  3365.                                      - 48 -
  3366.  
  3367.  
  3368.  
  3369.        GRAD User's Manual                                    June 7, 1987
  3370.  
  3371.        15.1.3  XHLine
  3372.  
  3373.                ret=XHLine(x,y,boundary,leftx,rightx);
  3374.                int x,y,boundary,*leftx,*rightx;
  3375.                int ret;
  3376.  
  3377.        RETURN VALUE
  3378.             -1  is returned  if  (x,y)  is already in  boundary state or
  3379.        (x,y)  is  outside  the  window.  If  return  value  is  not  -1,
  3380.        coordinates of  the left  most and  right most point  of the line
  3381.        drawn are returned in leftx and rightx.
  3382.             
  3383.        DESCRIPTION
  3384.             You give any point (x,y)  and specify the  boundary state in
  3385.        the search.  A horizontal line will be drawn by extending  to the
  3386.        left  and right.  If value of boundary  is 0,  the drawing of the
  3387.        line in that direction stops when it encounters any  pixel in set
  3388.        state.  If the value of  boundary  is non-zero, the drawing stops
  3389.        when it encounters any pixel in  reset state.  The left  most and
  3390.        right  most  coordinates of the  line is returned.  Of course the
  3391.        line cannot go beyond the  window.  All pixels outside the window
  3392.        are considered in boundary state.
  3393.             
  3394.             The line will be drawn  using current plot  type and current
  3395.        line style.  If the point (x,y) is in boundary state, no dot will
  3396.        be drawn and -1 is returned.
  3397.             
  3398.        EXAMPLE
  3399.                VertLine(50,50,100,1);
  3400.                VertLine(150,50,100,1);
  3401.                XHLine(100,100,0,&leftx, &rightx);
  3402.  
  3403.             XHLine  will  draw  a  horizontal  line  from   (51,100)  to
  3404.        (149,100).  51  and  149  will be  returned  in  leftx and rightx
  3405.        respectively.
  3406.             
  3407.        FUNCTIONS INCLUDED
  3408.             none
  3409.  
  3410.        
  3411.        15.1.4  writec
  3412.  
  3413.                writec(x,y,ch,width,height,options);
  3414.                int x,y,ch,*width,*height,options);
  3415.  
  3416.        RETURN VALUE
  3417.             width and height of the character box are  returned in width
  3418.        and height field in the parameter list.
  3419.             
  3420.        DESCRIPTION
  3421.             writec output a single character (ch) using current selected
  3422.        font to the current frame.  (x,y)  is the reference point for the
  3423.        character.  The actual meaning depends on the  options field. The
  3424.        interpretation of  options is  exactly the  same  as  the options
  3425.        field  in  WriteStr  except  it  does  not have  the text pointer
  3426.        movement options (category D).
  3427.             
  3428.             You should avoid using this function as much as possible.
  3429.  
  3430.                                      - 49 -
  3431.  
  3432.  
  3433.  
  3434.        GRAD User's Manual                                    June 7, 1987
  3435.  
  3436.  
  3437.        EXAMPLE
  3438.                writec(100,100,0x5f,&width, &height, 0);
  3439.  
  3440.        FUNCTIONS INCLUDED
  3441.             WriteStr, HorzLine, PlotType
  3442.  
  3443.  
  3444.  
  3445.  
  3446.  
  3447.  
  3448.  
  3449.  
  3450.  
  3451.  
  3452.  
  3453.  
  3454.  
  3455.  
  3456.  
  3457.  
  3458.  
  3459.  
  3460.  
  3461.  
  3462.  
  3463.  
  3464.  
  3465.  
  3466.  
  3467.  
  3468.  
  3469.  
  3470.  
  3471.  
  3472.  
  3473.  
  3474.  
  3475.  
  3476.  
  3477.  
  3478.  
  3479.  
  3480.  
  3481.  
  3482.  
  3483.  
  3484.  
  3485.  
  3486.  
  3487.  
  3488.  
  3489.  
  3490.  
  3491.  
  3492.  
  3493.  
  3494.  
  3495.                                      - 50 -
  3496.  
  3497.  
  3498.  
  3499.        GRAD User's Manual                                    June 7, 1987
  3500.  
  3501.        16  Advance Functions
  3502.  
  3503.             In  this  chapter,  all other  GRAD  functions  that  is not
  3504.        described  in  the preceding chapters  will  be  described. These
  3505.        functions are usually more advance.  Only experience users should
  3506.        try to use them. The functions to be described include:
  3507.             
  3508.                calcaddr        calculate address of the coordinate
  3509.                exchange        exchange the upper and lower byte of int
  3510.                fr_read         read a word from the current frame
  3511.                fr_write        write a word to the current frame
  3512.                phyaddr         calculate physical address 
  3513.                writetype       plot type other than AND, OR and XOR
  3514.  
  3515.        
  3516.        16.1  Functions Description
  3517.  
  3518.        16.1.1  calcaddr
  3519.  
  3520.                addr=calcaddr(x,y);
  3521.                int far *addr;
  3522.                int x,y;
  3523.  
  3524.        RETURN VALUE
  3525.             logical address  where  (x,y)  in  current  active  frame is
  3526.        located.
  3527.             
  3528.        DESCRIPTION
  3529.             It  will  calculate the address  where  the  pixel  (x,y) in
  3530.        current frame is located.  The address return may not be physical
  3531.        address.  You  must  not try to  read  or write  it directly. You
  3532.        should use the functions fr_read and fr_write to read and write.
  3533.             
  3534.        EXAMPLE
  3535.                addr=calcaddr(200,100);
  3536.                if (fr_read(addr) & DOTVALUE[200 & 0x0f]) {
  3537.                    printf("pixel (200,100) is set");
  3538.                } else {
  3539.                    printf("pixel (200,100) is reset");
  3540.                }
  3541.  
  3542.        
  3543.  
  3544.        
  3545.        16.1.2  exchange
  3546.  
  3547.                ret=exchange(value);
  3548.                unsigned int ret, value;
  3549.  
  3550.        RETURN VALUE
  3551.             the upper and lower byte of value is  swapped and  return as
  3552.        function result.
  3553.             
  3554.        DESCRIPTION
  3555.             The upper and lower byte of the parameter is swapped.
  3556.             
  3557.        EXAMPLE
  3558.                printf("%4x\n",exchange(0x1234));
  3559.  
  3560.                                      - 51 -
  3561.  
  3562.  
  3563.  
  3564.        GRAD User's Manual                                    June 7, 1987
  3565.  
  3566.  
  3567.             3412 is the value printed.
  3568.  
  3569.        
  3570.        16.1.3  fr_read
  3571.  
  3572.                ret=fr_read(addr);
  3573.                int far *addr;
  3574.                unsigned int ret;
  3575.  
  3576.        RETURN VALUE
  3577.             the value at the logical address addr
  3578.  
  3579.        DESCRIPTION
  3580.             It  reads the value by  the address given.  You  should only
  3581.        read from  the active frame  otherwise it is not  guaranteed that
  3582.        the result is correct.
  3583.             
  3584.        EXAMPLE
  3585.                addr=calcaddr(200,100);
  3586.                if (fr_read(addr) & DOTVALUE[200 & 0x0f]) {
  3587.                    printf("pixel (200,100) is set");
  3588.                } else {
  3589.                    printf("pixel (200,100) is reset");
  3590.                }
  3591.  
  3592.        
  3593.        16.1.4  fr_write
  3594.  
  3595.                fr_read(addr,value);
  3596.                int far *addr;
  3597.                unsigned int value;
  3598.  
  3599.        RETURN VALUE
  3600.             none
  3601.  
  3602.        DESCRIPTION
  3603.             It write the value into  the address given.  You should only
  3604.        write to the active frame otherwise it is not guaranteed that the
  3605.        result is correct. fr_write use the current plot type in writing.
  3606.             
  3607.        EXAMPLE
  3608.                addr=calcaddr(200,100);
  3609.                fr_write(addr, DOTVALUE[200 & 0x0f]);
  3610.  
  3611.             It writes the pixel (200,100).
  3612.  
  3613.        
  3614.        16.1.5  phyaddr
  3615.  
  3616.                addr=phyaddr(x,y);
  3617.                int x,y;
  3618.                int far *addr;
  3619.  
  3620.        RETURN VALUE
  3621.             physical address of the pixel (x,y) in current active frame.
  3622.  
  3623.        DESCRIPTION
  3624.  
  3625.                                      - 52 -
  3626.  
  3627.  
  3628.  
  3629.        GRAD User's Manual                                    June 7, 1987
  3630.  
  3631.             phyaddr  is  very  similar  to  calcaddr  except  the return
  3632.        address is always a physical address.  If the whole  frame is not
  3633.        accessible  all   the  time  (e.g.   JLASER),  immediately  after
  3634.        execution  of  phyaddr,   the  line  containing   (x,y)  will  be
  3635.        accessible.
  3636.             
  3637.        EXAMPLE
  3638.                int far *addr;
  3639.  
  3640.                addr=phyaddr(x,y);
  3641.  
  3642.        
  3643.        16.1.6  writetype
  3644.  
  3645.                writetype();
  3646.  
  3647.        RETURN VALUE
  3648.             none
  3649.  
  3650.        DESCRIPTION
  3651.             set the plot type to overwrite.  DON'T try to use  it unless
  3652.        you know what you are doing!
  3653.  
  3654.        EXAMPLE
  3655.                writetype();
  3656.  
  3657.  
  3658.  
  3659.  
  3660.  
  3661.  
  3662.  
  3663.  
  3664.  
  3665.  
  3666.  
  3667.  
  3668.  
  3669.  
  3670.  
  3671.  
  3672.  
  3673.  
  3674.  
  3675.  
  3676.  
  3677.  
  3678.  
  3679.  
  3680.  
  3681.  
  3682.  
  3683.  
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.                                      - 53 -
  3691.  
  3692.  
  3693.  
  3694.        GRAD User's Manual                                    June 7, 1987
  3695.  
  3696.        17  System Dependent Functions
  3697.  
  3698.             The functions described in  this  chapter  are  not standard
  3699.        GRAD library functions.  That  means they  are not always  in the
  3700.        library.  It depends on the output device configured in your GRAD
  3701.        system you are using.
  3702.  
  3703.        
  3704.        17.1  Functions Description
  3705.  
  3706.        17.1.1  settext
  3707.  
  3708.                settext();
  3709.  
  3710.        RETURN VALUE
  3711.             none
  3712.             
  3713.        DESCRIPTION
  3714.             It  is  available when  Hercules and Color  Graphics Card is
  3715.        used. The function is to change the display mode to text mode.
  3716.             
  3717.        EXAMPLE
  3718.                settext();
  3719.  
  3720.        
  3721.        17.1.2  setgraph
  3722.  
  3723.                setgraph();
  3724.  
  3725.        RETURN VALUE
  3726.             none
  3727.             
  3728.        DESCRIPTION
  3729.             It is  available when  Hercules  or  Color Graphics  Card is
  3730.        used.  The  function  is to change  the display mode  to graphics
  3731.        mode.
  3732.             
  3733.        EXAMPLE
  3734.                settext();
  3735.  
  3736.        
  3737.  
  3738.        17.1.3  initjlsr
  3739.  
  3740.                initjlsr();
  3741.  
  3742.        RETURN VALUE
  3743.             none
  3744.  
  3745.        DESCRIPTION
  3746.             This is  used  to  initialize  the JLASER  mode  to allocate
  3747.        memory for graphics data. You are not normally required to use it
  3748.        because it is included in GRADinit.
  3749.             
  3750.        EXAMPLE
  3751.                initjlsr();
  3752.  
  3753.        
  3754.  
  3755.                                      - 54 -
  3756.  
  3757.  
  3758.  
  3759.        GRAD User's Manual                                    June 7, 1987
  3760.  
  3761.        17.1.4  cleanjlsr
  3762.  
  3763.                cleanjlsr();
  3764.  
  3765.        RETURN VALUE
  3766.             none
  3767.  
  3768.        DESCRIPTION
  3769.             This is used to clean up the JLASER mode  by deallocate  the
  3770.        memory for graphics data. You are not normally required to use it
  3771.        because it is included in cleanup;
  3772.             
  3773.        EXAMPLE
  3774.                cleanjlsr();
  3775.  
  3776.        
  3777.  
  3778.        17.1.5  dumpjlsr
  3779.  
  3780.                dumpjlsr();
  3781.  
  3782.        RETURN VALUE
  3783.             none
  3784.  
  3785.        DESCRIPTION
  3786.             dumpjlsr will activate JLASER card to dump the memory to the
  3787.        LASER printer.  You may  also  print  the  data  in  memory using
  3788.        PrintFrame.
  3789.             
  3790.        EXAMPLE
  3791.             dumpjlsr();
  3792.  
  3793.  
  3794.  
  3795.  
  3796.  
  3797.  
  3798.  
  3799.  
  3800.  
  3801.  
  3802.  
  3803.  
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.                                      - 55 -
  3821.  
  3822.  
  3823.  
  3824.        GRAD User's Manual                                    June 7, 1987
  3825.  
  3826.        18  GRAD Global Variables
  3827.  
  3828.             Some of the variables in GRAD may be  used by the  user. You
  3829.        should have at least 2  months of experience with GRAD before you
  3830.        try to use these variables.
  3831.  
  3832.        
  3833.        18.1  TEN_MS
  3834.  
  3835.                int TEN_MS;
  3836.  
  3837.        DESCRIPTION
  3838.             TEN_MS contains  a value that  is proportion to  the central
  3839.        processor speed.  It is only a relative number and  the value may
  3840.        not be the same when GRAD is run twice  in a row  but they should
  3841.        be close.
  3842.             
  3843.             A IBM PC/XT running  at 4.77MHz gives  a count approximately
  3844.        equal to  333.  If  a processor is  ten times  faster,  the value
  3845.        should be about 3330.
  3846.  
  3847.        
  3848.        18.2  DOTVALUE
  3849.  
  3850.                unsigned int DOTVALUE[16]
  3851.  
  3852.        DESCRIPTION
  3853.             DOTVALUE gives the relative  dot position  in  a  word. Each
  3854.        word comprise 16  dots numbered from 0  to 15.  Dot 0 is the left
  3855.        most dot and 15 is the right most dot when display.
  3856.             
  3857.             DOTVALUE[n] where n is number from 0  to 15  gives the value
  3858.        of  the corresponding dot  in  the  word.  See  also  fr_read and
  3859.        fr_write.
  3860.  
  3861.        
  3862.        18.3  PRE_GRAD_ERR_LEVEL, POST_GRAD_ERR_LEVEL
  3863.  
  3864.                int PRE_ERROR_LEVEL, POST_ERROR_LEVEL;
  3865.  
  3866.        DESCRIPTION
  3867.             The error level in GRAD runs  from 0  to 10. PRE_ERROR_LEVEL
  3868.        defines the  lowest error level  you want to take  control before
  3869.        the  GRAD  default  error  handling  routine  process  the error.
  3870.        POST_ERROR_LEVEL defines  the lowest error level you want to take
  3871.        control  after GRAD  default error  handling  routines  print the
  3872.        error message and before it aborts the program or does recovery.
  3873.             
  3874.             See also PRE_ERROR_FUNC,  POST_ERROR_FUNC and error handling
  3875.        in the chapter "Advance Topics".
  3876.  
  3877.        
  3878.        18.4  PRE_ERROR_FUNC, POST_ERROR_FUNC
  3879.  
  3880.                void (*PRE_ERROR_FUNC)(), (*POST_ERROR_FUNC)();
  3881.  
  3882.        DESCRIPTION
  3883.             The declaration of the functions should be like this:
  3884.  
  3885.                                      - 56 -
  3886.  
  3887.  
  3888.  
  3889.        GRAD User's Manual                                    June 7, 1987
  3890.  
  3891.                
  3892.                #include <stdarg.h>
  3893.                
  3894.                int user_error_routine();
  3895.                extern (*PRE_ERROR_FUNC)();
  3896.                 .
  3897.                 .
  3898.                 .
  3899.                main()
  3900.                {
  3901.                 .
  3902.                 .
  3903.                        PRE_ERROR_LEVEL=4;  /* or the level you want */
  3904.                        PRE_ERROR_FUNC=user_error_routine;
  3905.                 .
  3906.                 .
  3907.                }
  3908.                
  3909.                void user_error_routine(error_level, error_nu, arg_ptr)
  3910.                int error_level, error_nu;
  3911.                va_list arg_ptr;        /* points to additional argument
  3912.                                           from caller */
  3913.                {
  3914.                 .
  3915.                 .
  3916.                }
  3917.                
  3918.             It is similar for POST_ERROR_FUNC.
  3919.  
  3920.        
  3921.        18.5  SPACING_FUNC
  3922.  
  3923.                int (*SPACING_FUNC)();
  3924.  
  3925.        DESCRIPTION
  3926.             This is for used  with  WriteStr.  See the section on "using
  3927.        SPACING_FUNC" in the chapter "Advance Topics".
  3928.             
  3929.  
  3930.        
  3931.        18.6  XLIMIT, YLIMIT
  3932.  
  3933.                int XLIMIT, YLIMIT;
  3934.  
  3935.        DESCRIPTION
  3936.             They are the maximum  physical  coordinates  in  the current
  3937.        frame.  They change when active frame change. You must not change
  3938.        these values.
  3939.  
  3940.        
  3941.        18.7  ORGX, ORGY
  3942.  
  3943.                int ORGX, ORGY;
  3944.  
  3945.        DESCRIPTION
  3946.             (ORGX,  ORGY)  is the  physical coordinate of  the origin in
  3947.        logical coordinate system.
  3948.  
  3949.  
  3950.                                      - 57 -
  3951.  
  3952.  
  3953.  
  3954.        GRAD User's Manual                                    June 7, 1987
  3955.  
  3956.        18.8  WINX1, WINX2, WINY1, WINY2
  3957.  
  3958.                int WINX1, WINX2, WINY1, WINY2;
  3959.  
  3960.        DESCRIPTION
  3961.             WINX1,  WINX2,  WINY1  and WINY2  stores the lower and upper
  3962.        limit of x coordinate and lower and upper limit  of  y coordinate
  3963.        of the current window respectively.
  3964.  
  3965.  
  3966.  
  3967.  
  3968.  
  3969.  
  3970.  
  3971.  
  3972.  
  3973.  
  3974.  
  3975.  
  3976.  
  3977.  
  3978.  
  3979.  
  3980.  
  3981.  
  3982.  
  3983.  
  3984.  
  3985.  
  3986.  
  3987.  
  3988.  
  3989.  
  3990.  
  3991.  
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.                                      - 58 -
  4016.  
  4017.  
  4018.  
  4019.        GRAD User's Manual                                    June 7, 1987
  4020.  
  4021.        19  Advance Topics
  4022.  
  4023.        19.1  Error Handling
  4024.  
  4025.             When GRAD functions detects a error,  they will call GRADerr
  4026.        with a error level code and error number.  It will issue an error
  4027.        message and takes appropriate  action. However GRAD also provides
  4028.        a  simple  way for  the  users  to  take  control  when  error is
  4029.        detected. There are four variables declared for error handling:
  4030.  
  4031.                int PRE_ERROR_LEVEL, POST_ERROR_LEVEL;
  4032.                void (*PRE_ERROR_FUNC)(), (*POST_ERROR_FUNC)();
  4033.                
  4034.             Firstly,  let's talk  about the  error  level  in  GRAD. All
  4035.        errors in GRAD is classified into 4  categories -- Warning (level
  4036.        2),  Recoverable Error (level  4),  Unrecoverable Error (level 6)
  4037.        and GRAD Program Error (level 10).
  4038.             
  4039.             The default action in GRAD is to print an error  message for
  4040.        all level of error. If that is a level 2 error (warning), it will
  4041.        return  control to  the program.  Otherwise,  it  will  abort the
  4042.        program.
  4043.             
  4044.             You may change the default action of GRADerr by changing the
  4045.        four variables  mentioned  above.  You  may  take  control before
  4046.        GRADerr  issues  an  error message or  after. PRE_ERROR_LEVEL and
  4047.        POST_ERROR_LEVEL defines the lowest  level of  error you  want to
  4048.        see before GRAD issues an error or after. When GRADerr finds that
  4049.        you want to  take control,  it will call the function  defined in
  4050.        PRE_ERROR_FUNC   or   POST_ERROR_FUNC.   If   PRE_ERROR_LEVEL  or
  4051.        POST_ERROR_LEVEL is  greater than  or  equal to  10 (GRAD Program
  4052.        Error),  user error routine will never be  called. GRADerr always
  4053.        handle level 10 and above error.
  4054.             
  4055.             After functions defined in PRE_ERROR_FUNC or POST_ERROR_FUNC
  4056.        have  processed the error situation,  they may  return control to
  4057.        GRADerr, abort the program by calling cleanup or do a longjmp. If
  4058.        user  program takes control using  PRE_ERROR_FUNC,  error message
  4059.        will not be issued by GRADerr even after it takes  control again.
  4060.        However, both PRE_ERROR_FUNC and POST_ERROR_FUNC may be called if
  4061.        error level is greater than PRE_ERROR_LEVEL and POST_ERROR_LEVEL.
  4062.             
  4063.             There is no way to continue the execution of a GRAD function
  4064.        if it detects a error condition with  error level greater  than 2
  4065.        (warning).
  4066.             
  4067.             Users may define  there own error level and  use  GRADerr to
  4068.        handle that.  In that case, you must write your own user handling
  4069.        routine  or  modify GRADerr  (not recommended).  Below is a short
  4070.        example.
  4071.  
  4072.        
  4073.                #include <stdio.h>
  4074.                #include <GRADVAR.h>
  4075.                #include <stdarg.h>
  4076.                
  4077.                void usererror1(), usererror2();
  4078.                
  4079.  
  4080.                                      - 59 -
  4081.  
  4082.  
  4083.  
  4084.        GRAD User's Manual                                    June 7, 1987
  4085.  
  4086.                main()
  4087.                {
  4088.                    char line[80];
  4089.                
  4090.                    GRADinit();
  4091.                    setgraph();
  4092.                    PRE_ERROR_LEVEL=4;
  4093.                    PRE_ERROR_FUNC=usererror1;
  4094.                    POST_ERROR_LEVEL=2;
  4095.                    POST_ERROR_FUNC=usererror2;
  4096.                    while (1) {
  4097.                        CreateFrame(960,792);
  4098.                        PlotType(1);
  4099.                        HorzLine(10,280,XLIMIT,25);
  4100.                        PlotType(0);
  4101.                        ReadStr(line,80,10,300,2,0x5f,0x5f);
  4102.                        LoadFont(line);
  4103.                    }
  4104.                }
  4105.                
  4106.                void usererror1(errlevel, errnu, arg_ptr)
  4107.                int errlevel, errnu;
  4108.                va_list arg_ptr;
  4109.                {
  4110.                    extern char *GRADERRMSG[];
  4111.                
  4112.                    printf("I am usererror 1:");
  4113.                    vprintf(GRADERRMSG[errnu],arg_ptr);
  4114.                    printf("\n");
  4115.                }
  4116.                
  4117.                void usererror2(errlevel, errnu, arg_ptr)
  4118.                int errlevel, errnu;
  4119.                va_list arg_ptr;
  4120.                {
  4121.                    printf("I am usererror2\n");
  4122.                }
  4123.                
  4124.             
  4125.             This program will  get error very  soon.  You can  type in a
  4126.        wrong font  file  name  and get a level  2  error.  After several
  4127.        times,  you will get out of memory  error (level  6) because each
  4128.        new frame occupy almost 93K bytes of memory. 
  4129.  
  4130.        
  4131.        19.2  Using SPACING_FUNC
  4132.  
  4133.             The function which address is stored  in SPACING_FUNC should
  4134.        return a integer.  Zero  means go  on.  A  non-zero  values tells
  4135.        WriteStr to stop immediately.  It may also modify  the content of
  4136.        the some of the variables  in WriteStr through the  address given
  4137.        in the parameters.
  4138.             
  4139.             Below is a simple example of using SPACING_FUNC. The spacing
  4140.        between the characters increase by 2 every time.
  4141.                
  4142.                #include <stdio.h>
  4143.                #include <GRADVAR.h>
  4144.  
  4145.                                      - 60 -
  4146.  
  4147.  
  4148.  
  4149.        GRAD User's Manual                                    June 7, 1987
  4150.  
  4151.                #include <GRADio.h>
  4152.                
  4153.                int increasing();
  4154.                
  4155.                int spacing;
  4156.                
  4157.                main()
  4158.                {  int x,y;
  4159.                
  4160.                   GRADinit();
  4161.                   setgraph();
  4162.                   spacing=0;
  4163.                   SPACING_FUNC=increasing;
  4164.                   WriteStr(VAR_MOVE,0,10,100,
  4165.                           "This is a special test 123456",0,0);
  4166.                   getch();
  4167.                   settext();
  4168.                   cleanup(0);
  4169.                }
  4170.                
  4171.                increasing(curx, cury, w, h, remaining)
  4172.                int *curx, *cury, w, h;
  4173.                char *remaining;
  4174.                {
  4175.                    *curx+=w+spacing;
  4176.                    spacing+=2;
  4177.                    return(0);
  4178.                }
  4179.                
  4180.  
  4181.             The  function increasing will  only get  control if VAR_MOVE
  4182.        option is used in WriteStr.  Every time when it gets  control, it
  4183.        has five  parameters  --  curx,  cury is  the  coordinate  of the
  4184.        reference point of  the character just  written.  w and h are the
  4185.        width and height  of  the character  box  of  the  character just
  4186.        written.  remaining points to the remaining part of the string to
  4187.        be written.  You may modify the remaining part  of  the string on
  4188.        the fly.  For example,  you may set the next character to null so
  4189.        that  WriteStr  will  terminate immediately.  Of  course  you may
  4190.        return a non-zero value to terminate WriteStr too.
  4191.             
  4192.             Another application of SPACING_FUNC is  to do justification.
  4193.        On the first  call  to  WriteStr,  specify  NO_WRITE  and collect
  4194.        information  on  the line.  Then call  WriteStr  again  to insert
  4195.        microspaces to justify the line.
  4196.             
  4197.             Within  SPACING_FUNC,  you  may  call  other  GRAD functions
  4198.        including  WriteStr  too!  But  be  careful,  the  loop  must  be
  4199.        terminate in some way,  otherwise you will get the stack overflow
  4200.        error very soon.
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.                                      - 61 -
  4211.  
  4212.  
  4213.  
  4214.        GRAD User's Manual                                    June 7, 1987
  4215.  
  4216.        20  Sample Programs
  4217.  
  4218.        20.1  MPrint and Interp
  4219.  
  4220.        USAGE
  4221.                MPrint [options] GRAD-command-file text-file-to-be merge
  4222.  
  4223.                Interp GRAD-command-file
  4224.  
  4225.        EXAMPLE
  4226.                Mprint -v1 test.gcm test.txt
  4227.  
  4228.             Print graphics data in high density.
  4229.  
  4230.        DESCRIPTION
  4231.             Below are the simple syntax rules for Interp and Mprint.
  4232.  
  4233.           ` ' means optional, | means or , { } means selection
  4234.  
  4235.           STMT := [ VARIABLE = ] FUNCTION
  4236.           VARIABLE := identifier
  4237.           FUNCTION := identifier ( PARAMETERS ) ;
  4238.           PARAMETERS := PARAMETER , PARAMETERS | PARAMETER
  4239.           PARAMETER := EXPRESSION
  4240.  
  4241.           EXPRESSION := NUMBER | STRING | VARIABLE | & VARIABLE | COLUMN
  4242.                           | LINE
  4243.           NUMBER := +NATURAL | -NATURAL
  4244.           NATURAL := 0xHHHH | decimal digits
  4245.           STRINGS := "character string"
  4246.           H := decimal digits | A | B | C | D | E | F | a | b | c
  4247.                   | d | e | f
  4248.           COLUMN := [ {C|c}NATURAL `, NATURAL' ]
  4249.           LINE := [ {L|l}NATURAL `, NATURAL' ]
  4250.  
  4251.             
  4252.             In  order to  facilitate  the calculation the coordinates on
  4253.        the  paper in  MPrint,  you may specify a coordinate in  terms of
  4254.        line and column number. Both line and column number start from 1.
  4255.        The  calculations  are based on  the character  width  and height
  4256.        setting.  You may change those values using  command line options
  4257.        in Mprint but Interp always use the default values in Mprint.
  4258.             
  4259.             No  variables can be  declared  but there  are  a  number of
  4260.        pre-declared variables.
  4261.          a. temp1,  temp2, temp3, env1, env2, env3, font1, font2, font3,
  4262.             font4,  frame1,  frame2,  frame3,  x1,  x2,  y1,  y2 are all
  4263.             integer variables.
  4264.          
  4265.          b. line is a character pointer to a 132-byte area. It is mainly
  4266.             for ReadStr function.
  4267.          
  4268.          c. pattern1,  pattern2  and pattern3 are pattern definition for
  4269.             use with PatternFill only.
  4270.          
  4271.             
  4272.  
  4273.  
  4274.  
  4275.                                      - 62 -
  4276.  
  4277.  
  4278.  
  4279.        GRAD User's Manual                                    June 7, 1987
  4280.  
  4281.             '&'  operator can only be used with integer  variables only.
  4282.        Moreover, only integer variables can appear on the left hand side
  4283.        of '=' (assignment).
  4284.             
  4285.             No any kind  of  arithmetic  operations  is  allowed in both
  4286.        Mprint  and  Interp.  However,  you  may  draw  lines  with  same
  4287.        coordinate numbers but at different location by setting origin at
  4288.        different coordinates.
  4289.             
  4290.             PrintPage  in  Interp  is  a  dummy  function.  Execution of
  4291.        PrintPage  in  Interp  will  suspend  the  interpretation  of the
  4292.        command  file  until  any   key  is  pressed  on   the  keyboard.
  4293.        Furthermore, after a key is pressed, the screen will be cleared.
  4294.             
  4295.             PrintPage  in Mprint will  merge print the  current selected
  4296.        frame and the text file if  specified.  The frame will be cleared
  4297.        after printing.
  4298.             
  4299.             MPrint also  provides  a  number  of  options  which  is not
  4300.        provided in Interp. The number inside the parentheses
  4301.             
  4302.           -W   frame width (960)
  4303.           -H   frame height (792)
  4304.           -w   character width in terms of pixels (12)
  4305.           -h   character height in terms of pixels (12)
  4306.           -c   column offset (0)
  4307.           -r   row offset (0)
  4308.           -p   line per page (66)
  4309.           -d   horizontal density (4)
  4310.           -v   vertical density (0)
  4311.           
  4312.             All the default value is for EPSON printer.  You may need to
  4313.        change the default values for different printer.
  4314.             
  4315.             There are a number of examples  for MPrint  and Interp. They
  4316.        illustrate most  of  the features  of Interp and MPrint.  You can
  4317.        learn a lot more about GRAD library by studying those examples.
  4318.  
  4319.        
  4320.        20.2  Rotate
  4321.  
  4322.        USAGE
  4323.                rotate input-FON-file output-FON-file
  4324.  
  4325.        EXAMPLE
  4326.                rotate AMR7.fon AMR7U.fon
  4327.  
  4328.        DESCRIPTION
  4329.             The input and output font file name cannot be the  same. The
  4330.        naming convention is to  append U,  R or D after the  normal font
  4331.        file name  to  indicate  that  font file is  normally for writing
  4332.        upward, to the right or downward.
  4333.             
  4334.             This  program will  rotate  a  font  file  in anti-clockwise
  4335.        direction  for 90  degree.  For example,  AMR7.fon after rotation
  4336.        should have the name AMR7U.fon.  If it is rotated again, the file
  4337.        name should become AMR7R.fon.
  4338.  
  4339.  
  4340.                                      - 63 -
  4341.  
  4342.  
  4343.  
  4344.        GRAD User's Manual                                    June 7, 1987
  4345.  
  4346.        20.3  Size
  4347.  
  4348.        USAGE
  4349.                size -s# [options] input-file output-file
  4350.  
  4351.        EXAMPLE
  4352.                size -s1 e6x8.fon e12x8.fon
  4353.  
  4354.        DESCRIPTION
  4355.             This program  is  to  change  the  size  of  the  font file.
  4356.        Allowable options are:
  4357.             
  4358.           -s0  reduce height by half
  4359.           -s1  double the height
  4360.           -s2  double the width
  4361.           -m0  ink dominate    (default)
  4362.           -m1  prefer ink
  4363.           -m2  prefer white space
  4364.           -m3  white space dominate
  4365.           
  4366.             -m option is only useful in reducing  the size  of the font.
  4367.        During reduction,  several pixels will be reduced to 1  pixel. If
  4368.        ink donimate option is used,  the resulting pixel is black if any
  4369.        one  of  the source  pixels  is black.  Similarly for white space
  4370.        dominate.  If prefer ink option  is used,  the resulting pixel is
  4371.        black if the number of black pixel is  more than or  equal to the
  4372.        number of white pixel.  If prefer white space option is used, the
  4373.        resulting  pixel is  black if the  number of black pixel  is MORE
  4374.        than the number of white pixel.
  4375.             
  4376.             In  this version  of size,  -m0  and -m1, -m2 and-m3 are the
  4377.        same. In order to provide future compatibility, all 4 options are
  4378.        valid.
  4379.  
  4380.        
  4381.        20.4  DispFont
  4382.  
  4383.        USAGE
  4384.                DispFont
  4385.  
  4386.        DESCRIPTION
  4387.             Enter a font file name when it asks for one. Enter the ASCII
  4388.        code  of  the character you want  to  see.  The character and the
  4389.        enlarger  character will  be  displayed.  A return  or a negative
  4390.        ASCII number will terminate the program.
  4391.  
  4392.        
  4393.        20.5  SwPrt (Sideway)
  4394.  
  4395.        USAGE
  4396.                swprt [options] text-file-name
  4397.  
  4398.        EXAMPLE
  4399.                swprt -fAMR7D.fon -s35 -H1920 -W792 -L3 -v1 -d3 test.txt
  4400.  
  4401.        DESCRIPTION
  4402.             The options provided are: (values inside parentheses are the
  4403.        default value)
  4404.  
  4405.                                      - 64 -
  4406.  
  4407.  
  4408.  
  4409.        GRAD User's Manual                                    June 7, 1987
  4410.  
  4411.            
  4412.            -W  Width of the print out (792).  This is the  length of the
  4413.                frame created for output.  This value should  be a simple
  4414.                fraction (1/2,  1/3 or 1/4) or a integral multiple of the
  4415.                length of paper.  If -v1 (described below) option is used
  4416.                and -L (described below also)  is set to a  value greater
  4417.                than 1,  the width should  be a integral multiple  of the
  4418.                number of  vertical unit per point.  In  other words, for
  4419.                EPSON printer, the value is 3, for OKI Microline 192, the
  4420.                value is 2.
  4421.            
  4422.            -H  Height of the print out (960).  This is the  width of the
  4423.                paper.  This number is related to  the horizontal density
  4424.                (-d option) setting.
  4425.            
  4426.            -v  Vertical  density   (0).   Any  non-zero  value  will  be
  4427.                considered as 1. See PrintFrame for explanation.
  4428.            
  4429.            -d  Horizontal  density   (4).   Also   see   PrintFrame  for
  4430.                explanation.  This value is  suitable  for  EPSON printer
  4431.                only.  You should set it to 2 for OKI printer if you want
  4432.                to use other default values.
  4433.            
  4434.            -s  Spacing between any 2  base line (11). This value is very
  4435.                likely to  be changed  when different font file  is used.
  4436.                See -f option below.
  4437.            
  4438.            -f  Font file  name.  (S6X8D.fon)  This  is the  font used in
  4439.                printing.  When use  other font file,  remember to change
  4440.                the  spacing  between  lines  using  -s  option described
  4441.                above.
  4442.            
  4443.            -t  Top margin (36).  This is the margin on the right side of
  4444.                the paper.
  4445.            
  4446.            -b  Bottom margin (36).  This is the margin on the  left side
  4447.                of the paper.
  4448.            
  4449.            -L  Text length (1). This field controls the number of 'page'
  4450.                for the text.  If text length is set to 2, that means the
  4451.                width of the text is  twice the specified width  (-W). In
  4452.                this way, you may print very long data without creating a
  4453.                very  large frame.  The -L  setting times the  -W setting
  4454.                must  not exceed  30000.  This value should be  more than
  4455.                enough.
  4456.  
  4457.             The default values will print 132 characters by 80 lines per
  4458.        page on a EPSON compatible printer.
  4459.  
  4460.        
  4461.        20.6  Tex2GRAD
  4462.  
  4463.        USAGE
  4464.                TeX2GRAD TeX-PXL-file GRAD-FON-file
  4465.  
  4466.        EXAMPLE
  4467.                TeX2GRAD amr10.pxl amr10.fon
  4468.  
  4469.  
  4470.                                      - 65 -
  4471.  
  4472.  
  4473.  
  4474.        GRAD User's Manual                                    June 7, 1987
  4475.  
  4476.        DESCRIPTION
  4477.             TeX2GRAD  converts  a TeX pixel  files  to  GRAD  font file.
  4478.        During the conversion, ASCII character 32 (' ') is forced to be a
  4479.        space with width equal to 9/16 of the design size.
  4480.             
  4481.             The TeX pixel file must  be a  type 1002  pixel file and the
  4482.        magnification  field in the file  must contain  the resolution of
  4483.        the output  device  the pixel file  is designed for times  5. For
  4484.        example,  a pixel file  for  a  laser  printer  with  300dpi, the
  4485.        magnification  field must contain 1500  decimal.  The pixel files
  4486.        from TEXTSET meets all of the above requirements.
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.  
  4493.  
  4494.  
  4495.  
  4496.  
  4497.  
  4498.  
  4499.  
  4500.  
  4501.  
  4502.  
  4503.  
  4504.  
  4505.  
  4506.  
  4507.  
  4508.  
  4509.  
  4510.  
  4511.  
  4512.  
  4513.  
  4514.  
  4515.  
  4516.  
  4517.  
  4518.  
  4519.  
  4520.  
  4521.  
  4522.  
  4523.  
  4524.  
  4525.  
  4526.  
  4527.  
  4528.  
  4529.  
  4530.  
  4531.  
  4532.  
  4533.  
  4534.  
  4535.                                      - 66 -
  4536.  
  4537.  
  4538.  
  4539.        GRAD User's Manual                                    June 7, 1987
  4540.  
  4541.        Appendix A : Customizing of Printer Control Codes
  4542.  
  4543.        General Information
  4544.  
  4545.             Two printer  drivers  for  EPSON  FX-80  and  OKI  ML192 are
  4546.        distributed  with  the GRAD  library.  If  you have  one of these
  4547.        printers or  a  compatible  one,  you  just  need  to  follow the
  4548.        installation instruction and you will  be  able to print  on your
  4549.        printer. Otherwise, go on reading this chapter.
  4550.             
  4551.             You can only  configure GRAD  to use 8  bit graphics printer
  4552.        with the information here and the included source  files. If your
  4553.        graphics printer is 24-pin printer or it only accepts 7 bit data,
  4554.        you need the source code of GRAD library to do the configuration.
  4555.        Information for special customizing accompany the source code.
  4556.             
  4557.             To do customizing, you need a Microsoft C compiler version 4
  4558.        and you may need a macro assembler also in some cases.
  4559.             
  4560.             There are three files involved in the customizing process.
  4561.          a. prtcntl.c defines the  control  code  sequence  for printing
  4562.             graphics and paper feeding.
  4563.          b. prt.asm  contains routines for converting  data  in frame to
  4564.             data for printing.
  4565.          c. pframe controls  the number  of dots printer  vertically per
  4566.             pass and the number of dots per point.
  4567.          
  4568.             Each  of  these will  be  discussed later.  Firstly,  let me
  4569.        define some  of  the terms first.  A point in  publishing means a
  4570.        length approximately equal to  1/72  inch.  However, a point here
  4571.        means  the distance  between 2  pins on the  print head. Vertical
  4572.        unit  is  the  smallest  distance  that  the  printer   can  move
  4573.        vertically.  The length  of  both  point  and  vertical  unit are
  4574.        printer dependent.  However, a point must be an integral multiple
  4575.        (can be 1) of vertical unit.
  4576.             
  4577.        a. prtcntl.c
  4578.             In prtcntl.c,  there are 8 variables declared. 5 of them are
  4579.        structure prtcmd.  prtcmd is used to store printer  control codes
  4580.        sequence. It contains 5 members.
  4581.             
  4582.             length  the length of the sequence from 0 to 8.
  4583.             factor  the number that will multiple with the number to be
  4584.                     included in the control sequence.
  4585.             numh    the high order byte of the scaled number in the
  4586.                     sequence. The value can be from -1 to length-1. -1
  4587.                     means the high order byte is not used.
  4588.             numl    the low order byte of the scaled number in the
  4589.                     sequence. The value can be from -1 to length-1. -1
  4590.                     means the low order byte is not used.
  4591.             code    the code sequence is stored here. Max. number of
  4592.                     character is 8.
  4593.             
  4594.             GRAD requires 5 kind of control sequences.
  4595.             
  4596.             skp     control sequence for moving the paper forward a
  4597.                     certain number of points. Note, it is point not
  4598.                     vertical unit.
  4599.  
  4600.                                      - 67 -
  4601.  
  4602.  
  4603.  
  4604.        GRAD User's Manual                                    June 7, 1987
  4605.  
  4606.             skd     control sequence for moving the paper forward a
  4607.                     certain number of vertical unit. Only used when
  4608.                     SMALL_DOT option is used in PrintFrame.
  4609.             setp    set the line feed spacing of the printer to the
  4610.                     specified number of points. It is only used at the
  4611.                     end of PrintFrame to set the printer back to six
  4612.                     line per inch. If skp and skd does not affect the
  4613.                     line feed spacing, you may set setp to null by
  4614.                     setting the length field to 0.
  4615.             header  is a array of struct prtcmd. It contains control
  4616.                     sequence to turn the printer into different density
  4617.                     graphics mode. The sequence is output immediately
  4618.                     before the graphics data.
  4619.             endg    contains the control sequence that append at the end
  4620.                     of graphics data in order to terminate the graphics
  4621.                     mode and cause the printer to actually print out the
  4622.                     data.
  4623.             
  4624.        Other 3 variables are:
  4625.             
  4626.             MAXPSIZ is the maximum number of dots that the printer can
  4627.                     print in different density.
  4628.             NHEADER contains the number of entries in the array header
  4629.                     and MAXPSIZ. Don't forget to change this number when
  4630.                     you change the number of entries in header and
  4631.                     MAXPSIZ.
  4632.             sixlpi  is the value that will be used with setp to set the
  4633.                     printer back to 6 line per inch at the end of
  4634.                     PrintFrame.
  4635.             
  4636.        b. prt.asm
  4637.             It is a assembly  program to  convert data in frame  to data
  4638.        for printing.  The data in a frame is stored line by line and the
  4639.        printer  usually requires  data  to be send  8  (or more) lines a
  4640.        time. prt is the routine for conversion. prtgc is the routine for
  4641.        putting  data  into  the  buffer  and  optionally  do  additional
  4642.        checking for special  pattern.  See  the  case  studies  for more
  4643.        information.
  4644.             
  4645.        c. pframe.obj
  4646.             pframe controls the number  of vertical dots  sent each time
  4647.        and the number of vertical unit per point.  Source code of pframe
  4648.        is  not  included  with  GRAD  library.  However  two  version of
  4649.        pframe.obj is provided: (1) 8 dots each time and 3 vertical units
  4650.        per point (EPSON FX-80) (2) 8 dots each time and 2 vertical units
  4651.        per point (OKI ML192).
  4652.             
  4653.             
  4654.             In the remaining part of the chapter, we will study the code
  4655.        for EPSON printer and OKI printer in  order to  provide a example
  4656.        of customizing.
  4657.  
  4658.        
  4659.  
  4660.  
  4661.  
  4662.  
  4663.  
  4664.  
  4665.                                      - 68 -
  4666.  
  4667.  
  4668.  
  4669.        GRAD User's Manual                                    June 7, 1987
  4670.  
  4671.        EPSON FX-80 Driver Case Study
  4672.  
  4673.             IN EPSON FX-80  printer, it does not have a control sequence
  4674.        to forward the paper a specified number  of points.  So I have to
  4675.        set the line spacing to  the desired number  and do  a line feed.
  4676.        The sequence  for setting line spacing is  3  characters long and
  4677.        the fourth character is a line feed.
  4678.             
  4679.             The  length  of  each  vertical  unit is 1/216  inch but the
  4680.        length  of  a point is  1/72  =  3/216 inch. Therefore the factor
  4681.        field is  3  in skp.  Only  a one byte  value is  allowed  in the
  4682.        control sequence so the numh  field is  set to -1  (not used) and
  4683.        numl is set to 2  (the third character).  skd is set in a similar
  4684.        way except the factor field is 1  this time.  If you have a EPSON
  4685.        FX-80  manual,  you would  find  that  the  control  sequence for
  4686.        setting line  spacing is  not the same  as defined  in setp. setp
  4687.        contains two extra characters. These are for IBM graphics printer
  4688.        or compatibles but it should still work for FX-80 printer.
  4689.             
  4690.             EPSON printer requires a length field as part of the control
  4691.        sequence for graphics printing.  It requires the total  number of
  4692.        bytes of graphics data following the sequence.  The  length field
  4693.        is 16 bit. Therefore both the numh and numl fields are set.
  4694.             
  4695.             If your printer don't have 80  dots per inch  mode (640 dots
  4696.        per line on 8 inch paper), you may used the sequence for 240 dots
  4697.        per  inch  and  set  the  factor  field  to  3.  PrintFrame  will
  4698.        automatically insert 2  null characters after  each graphics data
  4699.        byte.
  4700.             
  4701.             endg for EPSON is just a return character.
  4702.             
  4703.             MAXPSIZ values are the number of  dots per inch times  8. If
  4704.        you have a FX-100,  the values should  be the number of  dots per
  4705.        inch times 13.5.
  4706.             
  4707.             If you look at prt.asm,  you would find  that the difference
  4708.        between EPSON and OKI driver is in two main area. Firstly in prt,
  4709.        FX-80  mode use rcl (rotate circular left) while OKI mode use rcr
  4710.        (rotate circular right).  It is because the least significant bit
  4711.        of each byte is printed at the bottom in FX-80  but it is printed
  4712.        at the top in ML192.  Another difference is in prtgc.  OKI has an
  4713.        additional check for 03.  It will be explained in the  case study
  4714.        for OKI ML192.
  4715.  
  4716.        
  4717.        OKI ML192 Driver Case Study
  4718.  
  4719.             OKI ML192  use a  scheme completely different from  FX-80 in
  4720.        printing graphics.  It has control sequence  for forwarding paper
  4721.        without  changing  the line  spacing setting.  Therefore  no setp
  4722.        sequence is  required.  Furthermore,  the line spacing before and
  4723.        after printing is the same and it may not be six line per inch.
  4724.             
  4725.             In ML192, it uses the control code 03 to enter graphics mode
  4726.        and  the sequence  03  02  to  exit from graphics  mode. No total
  4727.        length of  data  is  required  to  send  to  the printer.  If the
  4728.        graphics data  contains the pattern  03,  it has to be duplicated
  4729.  
  4730.                                      - 69 -
  4731.  
  4732.  
  4733.  
  4734.        GRAD User's Manual                                    June 7, 1987
  4735.  
  4736.        (i.e.  03  03)  to indicate the 03 is a data byte and not command
  4737.        code.  This  is  the   reason  for a special checking  for  03 in
  4738.        prt.asm in OKI mode.
  4739.             
  4740.             endg contains  03  02  to  indicate  end of  data  which are
  4741.        appended at the end of graphics data.
  4742.             
  4743.             sixlpi is not  used in OKI driver.  Therefore it can  be any
  4744.        value but it has to be defined.
  4745.  
  4746.        
  4747.        Additional Information
  4748.  
  4749.             Before you do the customizing,  you should first  try to see
  4750.        any  body  has done  the customizing for  your  printer  make the
  4751.        driver available on the BBS.
  4752.             
  4753.             When  you do  the customizing,  probably you  need to modify
  4754.        prtcntl.c  yourself.  But  you may  not  need  to  modify prt.asm
  4755.        because you may use the OKI or EPSON version.  Then  you choose a
  4756.        suitable version of  pframe  for  your  printer.  If  you  need a
  4757.        special version of pframe, you have to either buy the source code
  4758.        or  see other printer drivers available have  a  version suitable
  4759.        for you or not.  With the source  code and the knowledge of C and
  4760.        assembly language,  customizing for most kind of  printer will be
  4761.        easy. Additional information is provided with source code.
  4762.  
  4763.  
  4764.  
  4765.  
  4766.  
  4767.  
  4768.  
  4769.  
  4770.  
  4771.  
  4772.  
  4773.  
  4774.  
  4775.  
  4776.  
  4777.  
  4778.  
  4779.  
  4780.  
  4781.  
  4782.  
  4783.  
  4784.  
  4785.  
  4786.  
  4787.  
  4788.  
  4789.  
  4790.  
  4791.  
  4792.  
  4793.  
  4794.  
  4795.                                      - 70 -
  4796.  
  4797.  
  4798.  
  4799.        GRAD User's Manual                                    June 7, 1987
  4800.  
  4801.        Appendix B : Customizing of Output Device
  4802.  
  4803.             Customizing for output device have a lot  of variations. You
  4804.        may only need to change a single line to rewrite several routines
  4805.        in customizing.  You also need some experiences  with GRAD before
  4806.        trying  to  do  customizing  otherwise  it  is   very  difficult.
  4807.        Therefore  only  general information will  be  given.  You should
  4808.        study the source codes provided yourself to find out what  do you
  4809.        need to change.
  4810.             
  4811.             Three  routines   are  related  to  customizing.   They  are
  4812.        calcaddr.asm,  plottype.asm and ftable.c.  Most  of  the hardware
  4813.        dependent  values  are  defined  in  calcaddr.asm  including  the
  4814.        address of  video memory,  default  font pattern  address and the
  4815.        routines for calculating address  by giving x and  y coordinates.
  4816.        plottype.asm contains the lowest  level memory  accessing routine
  4817.        for reading and writing.  ftable.c contain code for  defining the
  4818.        characteristics of the output device.
  4819.  
  4820.             Three  drivers  are  provided  for  Color  graphics adapter,
  4821.        Hercules graphics adapter (full or half mode) and JLASER card. 
  4822.  
  4823.  
  4824.  
  4825.  
  4826.  
  4827.  
  4828.  
  4829.  
  4830.  
  4831.  
  4832.  
  4833.  
  4834.  
  4835.  
  4836.  
  4837.  
  4838.  
  4839.  
  4840.  
  4841.  
  4842.  
  4843.  
  4844.  
  4845.  
  4846.  
  4847.  
  4848.  
  4849.  
  4850.  
  4851.  
  4852.  
  4853.  
  4854.  
  4855.  
  4856.  
  4857.  
  4858.  
  4859.  
  4860.                                      - 71 -
  4861.  
  4862.  
  4863.  
  4864.        GRAD User's Manual                                    June 7, 1987
  4865.  
  4866.        Appendix C : Font File Structure
  4867.  
  4868.             There are 2 types of font files. They are distinguish by the
  4869.        type code  stored  in  each  font  file.  Each  of  them  will be
  4870.        described separately.
  4871.  
  4872.        
  4873.        Fixed Size Character (type 0)
  4874.  
  4875.             The File format is  shown below.  If that field is  a 2 byte
  4876.        integer,  lower byte (less significant)  will be stored first and
  4877.        then the higher  byte  (more significant).  The  word  inside the
  4878.        bracket is the field name.
  4879.             
  4880.           Byte         Description
  4881.           0            ID = 51 decimal
  4882.           1 to n-1     [comment] A string in ASCII terminated by a NULL
  4883.                        character. The string can be any length less than
  4884.                        or equal to 255.
  4885.           n            [type] The type code. 0 in fixed size font file
  4886.           n+1, n+2     [nochar] Number of character in this file
  4887.           n+3, n+4     [start] The starting number. For example, only
  4888.                        pattern for graphic ASCII characters are
  4889.                        available. That means the first pattern is for
  4890.                        ASCII 0x20. Therefore, this field should contains
  4891.                        0x0020.
  4892.           
  4893.           /* the fields below will be described in more detail later */
  4894.           n+5          [width] width of the character cell
  4895.           n+6          [ink-width] ink width of the pattern
  4896.           n+7          [ink-height] ink height of the pattern
  4897.           n+8          [left-margin] left-margin of the pattern
  4898.           n+9          [top-line] the highest line number
  4899.           n+10         [cell-height] height of the character cell
  4900.           n+11         [default] the default character number
  4901.           n+12 to n+15 reserved
  4902.           
  4903.           n+16 to end of file are the pattern information
  4904.           
  4905.             Let's  take  an   example  using  E9X14.fon   (a  font  file
  4906.        containing 9  by 14  patterns). The vales for byte n to byte n+11
  4907.        are:
  4908.             
  4909.             00 00 01 00   00 09 08 0E   00 0A 0E 7F
  4910.             
  4911.             The font file contains pattern in the format of  type 0 (1st
  4912.        byte).  The number of pattern is  256  (0x0100 2nd and 3rd bytes)
  4913.        and it starts it ASCII 0  (0x0000 4th and 5th byte). The width of
  4914.        each  character including spacing  is  9  dots  (0x09  6th byte).
  4915.        However,  only 8  dots (0x08  7th byte)  of data are given in the
  4916.        file  and the pattern given starts  at  the first  dot  (0x00 9th
  4917.        byte).  So  the 9th dots  is assumed to be  0.  The height of the
  4918.        character cell is 14  (0x0E 8th byte).  The pattern starts  at 10
  4919.        lines above the base  line.  That means the descendent  part is 3
  4920.        dots.  If a character given does not have a corresponding pattern
  4921.        in  the file  (greater than 255),  the ASCII  character 255 (0x7f
  4922.        last byte) will be written instead.
  4923.             
  4924.  
  4925.                                      - 72 -
  4926.  
  4927.  
  4928.  
  4929.        GRAD User's Manual                                    June 7, 1987
  4930.  
  4931.             The  pattern is  stored  line  by line according to  the ink
  4932.        width and ink height.  For  example,  a character pattern  of ink
  4933.        width equal to 9 and height equal to 14. 28 bytes are required to
  4934.        store one character.  The character when  display is  in the form
  4935.        below:
  4936.             
  4937.                             0     7 8    15
  4938.                            +-------+-------+
  4939.                            |   0   |   1   |
  4940.                            +-------+-------+
  4941.                            |   2   |   3   |
  4942.                            +-------+-------+
  4943.                              . . . . . . .
  4944.                            +-------+-------+
  4945.                            |   26  |   27  |
  4946.                            +-------+-------+
  4947.                            
  4948.             Only bits 0 to 8 of every 2 bytes are used. 
  4949.  
  4950.        
  4951.        Variable Size Character (type 1)
  4952.  
  4953.             The File format is  shown below.  If that field is  a 2 byte
  4954.        integer,  lower byte (less significant)  will be stored first and
  4955.        then the higher  byte  (more significant).  The  word  inside the
  4956.        bracket is the field name.
  4957.             
  4958.           Byte         Description
  4959.           0            ID = 51 decimal
  4960.           1 to n-1     [comment] A string in ASCII terminated by a NULL
  4961.                        character. The string can be any length less than
  4962.                        or equal to 255.
  4963.           n            [type] The type code. 1 in variable size font
  4964.                        file
  4965.           n+1, n+2     [nochar] Number of character in this file
  4966.           n+3, n+4     [start] The starting number. For example, only
  4967.                        pattern for graphic ASCII characters are
  4968.                        available. That means the first pattern is for
  4969.                        ASCII 0x20. Therefore, this field should contains
  4970.                        0x0020.
  4971.           
  4972.           n+5 to n+7   reserved
  4973.           n+8          [default] the default character number
  4974.           n+9 to n+15  reserved
  4975.           
  4976.           n+16 to n+21 width, ink width, left margin, top line, cell
  4977.                        height information of first character.
  4978.           n+22 to n+27 same kind of information for second character.
  4979.            .
  4980.            .           information of all characters in the file
  4981.            .
  4982.           n+16+6*nochar to end of the file are the pattern data of the
  4983.                        characters
  4984.           
  4985.             The pattern data  are stored  exactly  as  described  in the
  4986.        section  for  fixed  size  character  except  each  character are
  4987.        independent of each other.
  4988.  
  4989.  
  4990.                                      - 73 -
  4991.  
  4992.  
  4993.  
  4994.        GRAD User's Manual                                    June 7, 1987
  4995.  
  4996.        Appendix D : Block File Structure
  4997.  
  4998.             The format  of  a block file  is very simple.  It contains a
  4999.        header and then comes the data. The structure when represented in
  5000.        C syntax is like this:
  5001.             
  5002.                struct header_format {
  5003.                        unsigned char ID;
  5004.                        unsigned int header_length : 4;
  5005.                        unsigned int x_offset : 4;
  5006.                        int length, height;
  5007.                        int dummy;
  5008.                } ;
  5009.                
  5010.                struct blockfile {
  5011.                        struct header_format header;
  5012.                        int data[height][((x_offset+length+15) >> 4)];
  5013.                };
  5014.                
  5015.             The  ID  is  equal   to  101   decimal   in   this  version.
  5016.        header_length is in term of 4-bytes. That means the length of the
  5017.        header must be  multiple of 4  bytes.  The header_length field in
  5018.        block files created by GRAD contain the value 2  now  because the
  5019.        header length is  6  bytes plus 2  byte dummy. The maximum header
  5020.        length is hence 64 bytes. You may include your own information in
  5021.        the header but remember to change the header_length field.
  5022.             
  5023.             We  will return to  x_offset later.  Let's talk about length
  5024.        and  height  fields first.  length and height  contain the actual
  5025.        number  of  pixels  in  the  block  horizontally  and  vertically
  5026.        respectively. 
  5027.             
  5028.             Since the data  array  is  declared  as  integer  array, the
  5029.        number of bytes per line must be even. Since the length field can
  5030.        be any number,  that means some  of the  bits in the data  do not
  5031.        contain  useful  information.  In order to make  the program more
  5032.        efficient,  the starting bit of actual data  of each line  in the
  5033.        file is  the same  as that when  it is in  memory as part  of the
  5034.        frame.  x_offset is used to  store the starting  pixel number for
  5035.        the first word (2  byte) in each line. x_offset may contain value
  5036.        from 0 to 15. 
  5037.             
  5038.             The most significant bit of a byte is displayed  as the left
  5039.        most  pixel of the byte. The earlier bytes of the line are stored
  5040.        at the left of a  frame.  This is the same as Color  Graphics and
  5041.        Hercules Graphics.
  5042.  
  5043.  
  5044.  
  5045.  
  5046.  
  5047.  
  5048.  
  5049.  
  5050.  
  5051.  
  5052.  
  5053.  
  5054.  
  5055.                                      - 74 -
  5056.  
  5057.  
  5058.  
  5059.        GRAD User's Manual                                    June 7, 1987
  5060.  
  5061.        Appendix E : Functions Summary
  5062.  
  5063.        Function        Description
  5064.        Arc1            Draws arc (part of a circle)
  5065.        Arc2            Draws arc (part of a circle)
  5066.        ArcPoint        Gives 2 end points of Arc2 or Earc2
  5067.        BlockCopy       Copy a data block between 2 frames
  5068.        BlockLoad       Load a data block from disk
  5069.        BlockSave       Save a data block to disk
  5070.        Box             Draws a box
  5071.        calcaddr        Calculates the word address in byte of a point
  5072.        Circle          Draws a logical circle
  5073.        cleanup         Cleans up everything
  5074.        CopyBlock       Copys a block within or between frame(s)
  5075.        CreateFrame     Creates a new frame
  5076.        Dot             Draws a single dot
  5077.        Draw            Interprete a string of command
  5078.        Earc1           Draws arc (part of an ellipse)
  5079.        Earc2           Draws arc (part of an ellipse)
  5080.        Ellipse         Draws an ellipse
  5081.        EnvSave         Saves the environment
  5082.        EnvRsto         Restores the environment
  5083.        FillCircle      Draws a solid circle
  5084.        FillEllipse     Draws a solid ellipse
  5085.        fr_read         read a word
  5086.        fr_write        write a word according to plot type
  5087.        HorzLine        Draws a horizontal line of any width
  5088.        GRADinit        Initialize GRAD environment
  5089.        Line            Draws a line between any 2 points
  5090.        LoadFont        Loads a font file from disk
  5091.        NextXY          Gives next (x,y) location for ReadStr or WriteStr
  5092.        PatternFill     Fill the area by the pattern specified
  5093.        phyaddr         calculate physical address
  5094.        PlotType        Selects system plot type
  5095.        PrintFrame      Print a frame to Printer
  5096.        ReadStr         Read a line from standard input
  5097.        Rectangle       Draws a rectangle
  5098.        RelOrg          Set origin
  5099.        RemvFont        Removes a font from memory
  5100.        RemvFrame       Removes a frame from GRAD and release the memory
  5101.        ResetWin        Reset the window to the same size as the frame
  5102.        SelectFont      Selects the current font number
  5103.        SelectFrame     Selects the active frame
  5104.        SetOrg          Set origin
  5105.        SetStyle        Sets line style
  5106.        SetWin          Set a rectangular window
  5107.        SolidFill       Entirely fill a region
  5108.        VertLine        Draws a VertLine in any width
  5109.        writec          writes a single character
  5110.        writetype       set to over write
  5111.        WriteStr        writes a string
  5112.        XHLine          A horizontal line extends at both end
  5113.  
  5114.  
  5115.  
  5116.  
  5117.  
  5118.  
  5119.  
  5120.                                      - 75 -
  5121.  
  5122.  
  5123.  
  5124.        GRAD User's Manual                                    June 7, 1987
  5125.  
  5126.        Appendix F : System Limits
  5127.  
  5128.             There are two types of system limits. First type of limit is
  5129.        caused by  the compiler,  the  algorithms,  the  memory available
  5130.        ...etc.  If one  wants to change these limits,  a  lot of changes
  5131.        have to be made. Another kind of limit is just arbitrary. You may
  5132.        change these limits  by  changing  a constant  and re-compile the
  5133.        program provided you have the source codes, of course.
  5134.  
  5135.        
  5136.        Program Limits
  5137.  
  5138.        a. The  absolute  maximum physical  coordinate must be  less than
  5139.           +32767. In reality, physical coordinate can never get close to
  5140.           this number  because it is limited by  the maximum  frame size
  5141.           also.
  5142.  
  5143.        b. The range of  logical coordinate  must  be  within  -32768 and
  5144.           +32767.
  5145.  
  5146.        c. The maximum horizontal frame size is 4096. You may change this
  5147.           maximum by changing 2  or 3  modules but I think  4096 is more
  5148.           than enough in most cases.  The absolute maximum vertical size
  5149.           is 32767.  But you will run out of memory before you get close
  5150.           to this number.
  5151.  
  5152.        d. The  maximum length  of  the radius  for  Circle,  Arc1, Arc2,
  5153.           FillCircle must be less than 8192.
  5154.  
  5155.        e. For  Ellipse,  FillEllipse,  Earc1 and Earc2, square of one of
  5156.           the axes  times another axis  must  be less then  1E+9. If the
  5157.           length of both axis is the same, maximum length would be 1000.
  5158.           It should be sufficient for most  application except  when you
  5159.           are working on a high resolution output device such  as JLASER
  5160.           and you need a large ellipse.
  5161.  
  5162.        f. There are also limits on the length for HorzLine, VertLine and
  5163.           Line but they are limited by the frame size far before limited
  5164.           by the algorithm.
  5165.  
  5166.        
  5167.        Configuration Limits
  5168.  
  5169.        a. The maximum number of frame that can be exist at the same time
  5170.           including the default  frame  is  10.  This  is  controlled by
  5171.           NFRAME in source listing.
  5172.  
  5173.        b. The maximum number of font that can  be used at  the same time
  5174.           including the  font  in  ROM  is  10.  This  is  controlled by
  5175.           MAXNFONT in source listing.
  5176.  
  5177.        c. The  maximum number  of slot for saving  environment including
  5178.           slot 0 is 10. This is controlled by MAX_ENVSLOT.
  5179.  
  5180.        d. The maximum size of  a single character  is approximately 2000
  5181.           bytes.  That is about 120 by 120 pixels. This is controlled by
  5182.           the size of the array CFBUF.
  5183.  
  5184.  
  5185.                                      - 76 -
  5186.  
  5187.  
  5188.  
  5189.        GRAD User's Manual                                    June 7, 1987
  5190.  
  5191.        e. The maximum length of data on a single pass for the printer is
  5192.           2048  bytes.  This is also controlled by the size of the array
  5193.           CFBUF.
  5194.  
  5195.        f. There is no arbitrary limit on the length  of  string for draw
  5196.           and WriteStr except by the memory available and the compiler.
  5197.  
  5198.  
  5199.  
  5200.  
  5201.  
  5202.  
  5203.  
  5204.  
  5205.  
  5206.  
  5207.  
  5208.  
  5209.  
  5210.  
  5211.  
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.  
  5219.  
  5220.  
  5221.  
  5222.  
  5223.  
  5224.  
  5225.  
  5226.  
  5227.  
  5228.  
  5229.  
  5230.  
  5231.  
  5232.  
  5233.  
  5234.  
  5235.  
  5236.  
  5237.  
  5238.  
  5239.  
  5240.  
  5241.  
  5242.  
  5243.  
  5244.  
  5245.  
  5246.  
  5247.  
  5248.  
  5249.  
  5250.                                      - 77 -
  5251.  
  5252.  
  5253.  
  5254.        GRAD User's Manual                                    June 7, 1987
  5255.  
  5256.        Appendix G : Error Messages
  5257.  
  5258.             Below is  a list  of  all  possible  error  message  by GRAD
  5259.        functions.  In a strip down version of error handling routine, it
  5260.        may  only  print the error number.  So the error  number  is also
  5261.        given on the left of the message.
  5262.  
  5263.        Error no.
  5264.           0     "Undefined Error Number : %d"
  5265.           1     "invalid environment slot number in EnvSave - %d"
  5266.           2     "invalid environment slot number in EnvRsto - %d"
  5267.           3     "environment slot not used - %d"
  5268.           4     "disk access error in BlockSave"
  5269.           5     "bad block file"
  5270.           6     "file not found - %s"
  5271.           7     "too many frame opened"
  5272.           8     "not sufficient memory to create new frame - %d*%d"
  5273.           9     "insufficient stack size for Fill"
  5274.          10     "PROGRAM ERROR IN %s LINE %d"
  5275.          12     "bad font type - %d"
  5276.          13     "too many font files loaded"
  5277.          14     "bad font file"
  5278.          15     "not sufficient memory to load new font"
  5279.          16     "no more environment slot for Draw"
  5280.          17     "invalid command in Draw - %c%c"
  5281.          18     "wrong number of parameter given to %c%c in Draw"
  5282.          19     "a digit expected after '%' or '&' in Draw"
  5283.          20     "invalid marker number - %d"
  5284.          21     "disk error in reading font file"
  5285.  
  5286.  
  5287.  
  5288.  
  5289.  
  5290.  
  5291.  
  5292.  
  5293.  
  5294.  
  5295.  
  5296.  
  5297.  
  5298.  
  5299.  
  5300.  
  5301.  
  5302.  
  5303.  
  5304.  
  5305.  
  5306.  
  5307.  
  5308.  
  5309.  
  5310.  
  5311.  
  5312.  
  5313.  
  5314.  
  5315.                                      - 78 -
  5316.  
  5317.  
  5318.  
  5319.        GRAD User's Manual                                    June 7, 1987
  5320.  
  5321.        Appendix H : List of Header Files
  5322.  
  5323.             Below is the list of the header files for programs  that use
  5324.        the GRAD library.
  5325.  
  5326.        /*  GRADIO.H  */
  5327.        #define LEFT       0
  5328.        #define DOWN_LEFT  1
  5329.        #define DOWN       2
  5330.        #define DOWN_RIGHT 3
  5331.        #define RIGHT      4
  5332.        #define UP_RIGHT   5
  5333.        #define UP         6
  5334.        #define UP_LEFT    7
  5335.        #define BOTTOM_LEFT     0x00
  5336.        #define BOTTOM_CENTER   0x04
  5337.        #define BOTTOM_RIGHT    0x01
  5338.        #define TOP_LEFT        0x03
  5339.        #define TOP_CENTER      0x06
  5340.        #define TOP_RIGHT       0x02
  5341.        #define LEFT_CENTER     0x05
  5342.        #define RIGHT_CENTER    0x07
  5343.        #define CLEAR_CELL      0x10
  5344.        #define FILL_CELL       0x20
  5345.        #define INVERSE_CELL    0x30
  5346.        #define WRITE           0x00
  5347.        #define NO_WRITE        0x08
  5348.        #define AUTO_MOVE       0x0000
  5349.        #define FIX_MOVE        0x0100
  5350.        #define VAR_MOVE        0x0200
  5351.  
  5352.        /*  GRADARC.h  */
  5353.        #define UP_RIGHT 0x01
  5354.        #define RIGHT_UP 0x02
  5355.        #define RIGHT_DOWN 0x04
  5356.        #define DOWN_RIGHT 0x08
  5357.        #define DOWN_LEFT 0x10
  5358.        #define LEFT_DOWN 0x20
  5359.        #define LEFT_UP 0x40
  5360.        #define UP_LEFT 0x80
  5361.  
  5362.        #define UPPER_HALF 0xc3
  5363.        #define LOWER_HALF 0x3c
  5364.        #define LEFT_HALF 0xf0
  5365.        #define RIGHT_HALF 0x0f
  5366.  
  5367.        void Circle(), Arc1(), Arc2(), FillCircle();
  5368.        void Ellipse(), Earc1(), Earc2(), FillEllipse();
  5369.  
  5370.        /*  GRADENV.h  */
  5371.        int EnvSave(), EnvRsto();
  5372.  
  5373.        #define KEEP_SLOT     0x8000
  5374.        #define KEEP_WIN      0x0001
  5375.        #define KEEP_ORG      0x0002
  5376.        #define KEEP_STYLE    0x0004
  5377.        #define KEEP_PLOTTYPE 0x0008
  5378.        #define KEEP_FRAME    0x0010
  5379.  
  5380.                                      - 79 -
  5381.  
  5382.  
  5383.  
  5384.        GRAD User's Manual                                    June 7, 1987
  5385.  
  5386.        #define KEEP_FONT     0x0020
  5387.  
  5388.        /*  GRADVAR.h  */
  5389.        extern unsigned int DOTVALUE[];
  5390.        extern int XLIMIT, YLIMIT;
  5391.        extern int ORGX, ORGY;
  5392.        extern int TEN_MS;
  5393.        extern void (*PRE_ERROR_FUNC)(), (*POST_ERROR_FUNC)();
  5394.        extern int (*SPACING_FUNC)();
  5395.        extern int PRE_ERROR_LEVEL, POST_ERROR_LEVEL;
  5396.        extern int WINX1, WINX2, WINY1, WINY2;
  5397.  
  5398.  
  5399.  
  5400.  
  5401.  
  5402.  
  5403.  
  5404.  
  5405.  
  5406.  
  5407.  
  5408.  
  5409.  
  5410.  
  5411.  
  5412.  
  5413.  
  5414.  
  5415.  
  5416.  
  5417.  
  5418.  
  5419.  
  5420.  
  5421.  
  5422.  
  5423.  
  5424.  
  5425.  
  5426.  
  5427.  
  5428.  
  5429.  
  5430.  
  5431.  
  5432.  
  5433.  
  5434.  
  5435.  
  5436.  
  5437.  
  5438.  
  5439.  
  5440.  
  5441.  
  5442.  
  5443.  
  5444.  
  5445.                                      - 80 -
  5446.  
  5447.  
  5448.